Add m-esr52 at 52.6.0

1 files changed, 1625 insertions, 0 deletions

diff --git a/devtools/client/shared/widgets/view-helpers.js b/devtools/client/shared/widgets/view-helpers.js
new file mode 100644
index 000000000..4686d4e1c
--- /dev/null
+++ b/devtools/client/shared/widgets/view-helpers.js
@@ -0,0 +1,1625 @@
+/* -*- indent-tabs-mode: nil; js-indent-level: 2 -*- */
+/* vim: set ft=javascript ts=2 et sw=2 tw=80: */
+/* 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/. */
+"use strict";
+
+const {KeyCodes} = require("devtools/client/shared/keycodes");
+
+const PANE_APPEARANCE_DELAY = 50;
+const PAGE_SIZE_ITEM_COUNT_RATIO = 5;
+const WIDGET_FOCUSABLE_NODES = new Set(["vbox", "hbox"]);
+
+var namedTimeoutsStore = new Map();
+
+/**
+ * Inheritance helpers from the addon SDK's core/heritage.
+ * Remove these when all devtools are loadered.
+ */
+exports.Heritage = {
+  /**
+   * @see extend in sdk/core/heritage.
+   */
+  extend: function (prototype, properties = {}) {
+    return Object.create(prototype, this.getOwnPropertyDescriptors(properties));
+  },
+
+  /**
+   * @see getOwnPropertyDescriptors in sdk/core/heritage.
+   */
+  getOwnPropertyDescriptors: function (object) {
+    return Object.getOwnPropertyNames(object).reduce((descriptor, name) => {
+      descriptor[name] = Object.getOwnPropertyDescriptor(object, name);
+      return descriptor;
+    }, {});
+  }
+};
+
+/**
+ * Helper for draining a rapid succession of events and invoking a callback
+ * once everything settles down.
+ *
+ * @param string id
+ *        A string identifier for the named timeout.
+ * @param number wait
+ *        The amount of milliseconds to wait after no more events are fired.
+ * @param function callback
+ *        Invoked when no more events are fired after the specified time.
+ */
+const setNamedTimeout = function setNamedTimeout(id, wait, callback) {
+  clearNamedTimeout(id);
+
+  namedTimeoutsStore.set(id, setTimeout(() =>
+    namedTimeoutsStore.delete(id) && callback(), wait));
+};
+exports.setNamedTimeout = setNamedTimeout;
+
+/**
+ * Clears a named timeout.
+ * @see setNamedTimeout
+ *
+ * @param string id
+ *        A string identifier for the named timeout.
+ */
+const clearNamedTimeout = function clearNamedTimeout(id) {
+  if (!namedTimeoutsStore) {
+    return;
+  }
+  clearTimeout(namedTimeoutsStore.get(id));
+  namedTimeoutsStore.delete(id);
+};
+exports.clearNamedTimeout = clearNamedTimeout;
+
+/**
+ * Same as `setNamedTimeout`, but invokes the callback only if the provided
+ * predicate function returns true. Otherwise, the timeout is re-triggered.
+ *
+ * @param string id
+ *        A string identifier for the conditional timeout.
+ * @param number wait
+ *        The amount of milliseconds to wait after no more events are fired.
+ * @param function predicate
+ *        The predicate function used to determine whether the timeout restarts.
+ * @param function callback
+ *        Invoked when no more events are fired after the specified time, and
+ *        the provided predicate function returns true.
+ */
+const setConditionalTimeout = function setConditionalTimeout(id, wait,
+                                                             predicate,
+                                                             callback) {
+  setNamedTimeout(id, wait, function maybeCallback() {
+    if (predicate()) {
+      callback();
+      return;
+    }
+    setConditionalTimeout(id, wait, predicate, callback);
+  });
+};
+exports.setConditionalTimeout = setConditionalTimeout;
+
+/**
+ * Clears a conditional timeout.
+ * @see setConditionalTimeout
+ *
+ * @param string id
+ *        A string identifier for the conditional timeout.
+ */
+const clearConditionalTimeout = function clearConditionalTimeout(id) {
+  clearNamedTimeout(id);
+};
+exports.clearConditionalTimeout = clearConditionalTimeout;
+
+/**
+ * Helpers for creating and messaging between UI components.
+ */
+const ViewHelpers = exports.ViewHelpers = {
+  /**
+   * Convenience method, dispatching a custom event.
+   *
+   * @param nsIDOMNode target
+   *        A custom target element to dispatch the event from.
+   * @param string type
+   *        The name of the event.
+   * @param any detail
+   *        The data passed when initializing the event.
+   * @return boolean
+   *         True if the event was cancelled or a registered handler
+   *         called preventDefault.
+   */
+  dispatchEvent: function (target, type, detail) {
+    if (!(target instanceof Node)) {
+      // Event cancelled.
+      return true;
+    }
+    let document = target.ownerDocument || target;
+    let dispatcher = target.ownerDocument ? target : document.documentElement;
+
+    let event = document.createEvent("CustomEvent");
+    event.initCustomEvent(type, true, true, detail);
+    return dispatcher.dispatchEvent(event);
+  },
+
+  /**
+   * Helper delegating some of the DOM attribute methods of a node to a widget.
+   *
+   * @param object widget
+   *        The widget to assign the methods to.
+   * @param nsIDOMNode node
+   *        A node to delegate the methods to.
+   */
+  delegateWidgetAttributeMethods: function (widget, node) {
+    widget.getAttribute =
+      widget.getAttribute || node.getAttribute.bind(node);
+    widget.setAttribute =
+      widget.setAttribute || node.setAttribute.bind(node);
+    widget.removeAttribute =
+      widget.removeAttribute || node.removeAttribute.bind(node);
+  },
+
+  /**
+   * Helper delegating some of the DOM event methods of a node to a widget.
+   *
+   * @param object widget
+   *        The widget to assign the methods to.
+   * @param nsIDOMNode node
+   *        A node to delegate the methods to.
+   */
+  delegateWidgetEventMethods: function (widget, node) {
+    widget.addEventListener =
+      widget.addEventListener || node.addEventListener.bind(node);
+    widget.removeEventListener =
+      widget.removeEventListener || node.removeEventListener.bind(node);
+  },
+
+  /**
+   * Checks if the specified object looks like it's been decorated by an
+   * event emitter.
+   *
+   * @return boolean
+   *         True if it looks, walks and quacks like an event emitter.
+   */
+  isEventEmitter: function (object) {
+    return object && object.on && object.off && object.once && object.emit;
+  },
+
+  /**
+   * Checks if the specified object is an instance of a DOM node.
+   *
+   * @return boolean
+   *         True if it's a node, false otherwise.
+   */
+  isNode: function (object) {
+    return object instanceof Node ||
+           object instanceof Element ||
+           object instanceof DocumentFragment;
+  },
+
+  /**
+   * Prevents event propagation when navigation keys are pressed.
+   *
+   * @param Event e
+   *        The event to be prevented.
+   */
+  preventScrolling: function (e) {
+    switch (e.keyCode) {
+      case KeyCodes.DOM_VK_UP:
+      case KeyCodes.DOM_VK_DOWN:
+      case KeyCodes.DOM_VK_LEFT:
+      case KeyCodes.DOM_VK_RIGHT:
+      case KeyCodes.DOM_VK_PAGE_UP:
+      case KeyCodes.DOM_VK_PAGE_DOWN:
+      case KeyCodes.DOM_VK_HOME:
+      case KeyCodes.DOM_VK_END:
+        e.preventDefault();
+        e.stopPropagation();
+    }
+  },
+
+  /**
+   * Check if the enter key or space was pressed
+   *
+   * @param event event
+   *        The event triggered by a keypress on an element
+   */
+  isSpaceOrReturn: function (event) {
+    return event.keyCode === KeyCodes.DOM_VK_SPACE ||
+          event.keyCode === KeyCodes.DOM_VK_RETURN;
+  },
+
+  /**
+   * Sets a toggled pane hidden or visible. The pane can either be displayed on
+   * the side (right or left depending on the locale) or at the bottom.
+   *
+   * @param object flags
+   *        An object containing some of the following properties:
+   *        - visible: true if the pane should be shown, false to hide
+   *        - animated: true to display an animation on toggle
+   *        - delayed: true to wait a few cycles before toggle
+   *        - callback: a function to invoke when the toggle finishes
+   * @param nsIDOMNode pane
+   *        The element representing the pane to toggle.
+   */
+  togglePane: function (flags, pane) {
+    // Make sure a pane is actually available first.
+    if (!pane) {
+      return;
+    }
+
+    // Hiding is always handled via margins, not the hidden attribute.
+    pane.removeAttribute("hidden");
+
+    // Add a class to the pane to handle min-widths, margins and animations.
+    pane.classList.add("generic-toggled-pane");
+
+    // Avoid toggles in the middle of animation.
+    if (pane.hasAttribute("animated")) {
+      return;
+    }
+
+    // Avoid useless toggles.
+    if (flags.visible == !pane.classList.contains("pane-collapsed")) {
+      if (flags.callback) {
+        flags.callback();
+      }
+      return;
+    }
+
+    // The "animated" attributes enables animated toggles (slide in-out).
+    if (flags.animated) {
+      pane.setAttribute("animated", "");
+    } else {
+      pane.removeAttribute("animated");
+    }
+
+    // Computes and sets the pane margins in order to hide or show it.
+    let doToggle = () => {
+      // Negative margins are applied to "right" and "left" to support RTL and
+      // LTR directions, as well as to "bottom" to support vertical layouts.
+      // Unnecessary negative margins are forced to 0 via CSS in widgets.css.
+      if (flags.visible) {
+        pane.style.marginLeft = "0";
+        pane.style.marginRight = "0";
+        pane.style.marginBottom = "0";
+        pane.classList.remove("pane-collapsed");
+      } else {
+        let width = Math.floor(pane.getAttribute("width")) + 1;
+        let height = Math.floor(pane.getAttribute("height")) + 1;
+        pane.style.marginLeft = -width + "px";
+        pane.style.marginRight = -width + "px";
+        pane.style.marginBottom = -height + "px";
+      }
+
+      // Wait for the animation to end before calling afterToggle()
+      if (flags.animated) {
+        let options = {
+          useCapture: false,
+          once: true
+        };
+
+        pane.addEventListener("transitionend", () => {
+          // Prevent unwanted transitions: if the panel is hidden and the layout
+          // changes margins will be updated and the panel will pop out.
+          pane.removeAttribute("animated");
+
+          if (!flags.visible) {
+            pane.classList.add("pane-collapsed");
+          }
+          if (flags.callback) {
+            flags.callback();
+          }
+        }, options);
+      } else {
+        if (!flags.visible) {
+          pane.classList.add("pane-collapsed");
+        }
+
+        // Invoke the callback immediately since there's no transition.
+        if (flags.callback) {
+          flags.callback();
+        }
+      }
+    };
+
+    // Sometimes it's useful delaying the toggle a few ticks to ensure
+    // a smoother slide in-out animation.
+    if (flags.delayed) {
+      pane.ownerDocument.defaultView.setTimeout(doToggle,
+                                                PANE_APPEARANCE_DELAY);
+    } else {
+      doToggle();
+    }
+  }
+};
+
+/**
+ * A generic Item is used to describe children present in a Widget.
+ *
+ * This is basically a very thin wrapper around an nsIDOMNode, with a few
+ * characteristics, like a `value` and an `attachment`.
+ *
+ * The characteristics are optional, and their meaning is entirely up to you.
+ * - The `value` should be a string, passed as an argument.
+ * - The `attachment` is any kind of primitive or object, passed as an argument.
+ *
+ * Iterable via "for (let childItem of parentItem) { }".
+ *
+ * @param object ownerView
+ *        The owner view creating this item.
+ * @param nsIDOMNode element
+ *        A prebuilt node to be wrapped.
+ * @param string value
+ *        A string identifying the node.
+ * @param any attachment
+ *        Some attached primitive/object.
+ */
+function Item(ownerView, element, value, attachment) {
+  this.ownerView = ownerView;
+  this.attachment = attachment;
+  this._value = value + "";
+  this._prebuiltNode = element;
+  this._itemsByElement = new Map();
+}
+
+Item.prototype = {
+  get value() {
+    return this._value;
+  },
+  get target() {
+    return this._target;
+  },
+  get prebuiltNode() {
+    return this._prebuiltNode;
+  },
+
+  /**
+   * Immediately appends a child item to this item.
+   *
+   * @param nsIDOMNode element
+   *        An nsIDOMNode representing the child element to append.
+   * @param object options [optional]
+   *        Additional options or flags supported by this operation:
+   *          - attachment: some attached primitive/object for the item
+   *          - attributes: a batch of attributes set to the displayed element
+   *          - finalize: function invoked when the child item is removed
+   * @return Item
+   *         The item associated with the displayed element.
+   */
+  append: function (element, options = {}) {
+    let item = new Item(this, element, "", options.attachment);
+
+    // Entangle the item with the newly inserted child node.
+    // Make sure this is done with the value returned by appendChild(),
+    // to avoid storing a potential DocumentFragment.
+    this._entangleItem(item, this._target.appendChild(element));
+
+    // Handle any additional options after entangling the item.
+    if (options.attributes) {
+      options.attributes.forEach(e => item._target.setAttribute(e[0], e[1]));
+    }
+    if (options.finalize) {
+      item.finalize = options.finalize;
+    }
+
+    // Return the item associated with the displayed element.
+    return item;
+  },
+
+  /**
+   * Immediately removes the specified child item from this item.
+   *
+   * @param Item item
+   *        The item associated with the element to remove.
+   */
+  remove: function (item) {
+    if (!item) {
+      return;
+    }
+    this._target.removeChild(item._target);
+    this._untangleItem(item);
+  },
+
+  /**
+   * Entangles an item (model) with a displayed node element (view).
+   *
+   * @param Item item
+   *        The item describing a target element.
+   * @param nsIDOMNode element
+   *        The element displaying the item.
+   */
+  _entangleItem: function (item, element) {
+    this._itemsByElement.set(element, item);
+    item._target = element;
+  },
+
+  /**
+   * Untangles an item (model) from a displayed node element (view).
+   *
+   * @param Item item
+   *        The item describing a target element.
+   */
+  _untangleItem: function (item) {
+    if (item.finalize) {
+      item.finalize(item);
+    }
+    for (let childItem of item) {
+      item.remove(childItem);
+    }
+
+    this._unlinkItem(item);
+    item._target = null;
+  },
+
+  /**
+   * Deletes an item from the its parent's storage maps.
+   *
+   * @param Item item
+   *        The item describing a target element.
+   */
+  _unlinkItem: function (item) {
+    this._itemsByElement.delete(item._target);
+  },
+
+  /**
+   * Returns a string representing the object.
+   * Avoid using `toString` to avoid accidental JSONification.
+   * @return string
+   */
+  stringify: function () {
+    return JSON.stringify({
+      value: this._value,
+      target: this._target + "",
+      prebuiltNode: this._prebuiltNode + "",
+      attachment: this.attachment
+    }, null, 2);
+  },
+
+  _value: "",
+  _target: null,
+  _prebuiltNode: null,
+  finalize: null,
+  attachment: null
+};
+
+/**
+ * Some generic Widget methods handling Item instances.
+ * Iterable via "for (let childItem of wrappedView) { }".
+ *
+ * Usage:
+ *   function MyView() {
+ *     this.widget = new MyWidget(document.querySelector(".my-node"));
+ *   }
+ *
+ *   MyView.prototype = Heritage.extend(WidgetMethods, {
+ *     myMethod: function() {},
+ *     ...
+ *   });
+ *
+ * See https://gist.github.com/victorporof/5749386 for more details.
+ * The devtools/shared/widgets/SimpleListWidget.jsm is an implementation
+ * example.
+ *
+ * Language:
+ *   - An "item" is an instance of an Item.
+ *   - An "element" or "node" is a nsIDOMNode.
+ *
+ * The supplied widget can be any object implementing the following
+ * methods:
+ *   - function:nsIDOMNode insertItemAt(aIndex:number, aNode:nsIDOMNode,
+ *                                      aValue:string)
+ *   - function:nsIDOMNode getItemAtIndex(aIndex:number)
+ *   - function removeChild(aChild:nsIDOMNode)
+ *   - function removeAllItems()
+ *   - get:nsIDOMNode selectedItem()
+ *   - set selectedItem(aChild:nsIDOMNode)
+ *   - function getAttribute(aName:string)
+ *   - function setAttribute(aName:string, aValue:string)
+ *   - function removeAttribute(aName:string)
+ *   - function addEventListener(aName:string, aCallback:function,
+ *                               aBubbleFlag:boolean)
+ *   - function removeEventListener(aName:string, aCallback:function,
+ *                                  aBubbleFlag:boolean)
+ *
+ * Optional methods that can be implemented by the widget:
+ *   - function ensureElementIsVisible(aChild:nsIDOMNode)
+ *
+ * Optional attributes that may be handled (when calling
+ * get/set/removeAttribute):
+ *   - "emptyText": label temporarily added when there are no items present
+ *   - "headerText": label permanently added as a header
+ *
+ * For automagical keyboard and mouse accessibility, the widget should be an
+ * event emitter with the following events:
+ *   - "keyPress" -> (aName:string, aEvent:KeyboardEvent)
+ *   - "mousePress" -> (aName:string, aEvent:MouseEvent)
+ */
+const WidgetMethods = exports.WidgetMethods = {
+  /**
+   * Sets the element node or widget associated with this container.
+   * @param nsIDOMNode | object widget
+   */
+  set widget(widget) {
+    this._widget = widget;
+
+    // Can't use a WeakMap for _itemsByValue because keys are strings, and
+    // can't use one for _itemsByElement either, since it needs to be iterable.
+    this._itemsByValue = new Map();
+    this._itemsByElement = new Map();
+    this._stagedItems = [];
+
+    // Handle internal events emitted by the widget if necessary.
+    if (ViewHelpers.isEventEmitter(widget)) {
+      widget.on("keyPress", this._onWidgetKeyPress.bind(this));
+      widget.on("mousePress", this._onWidgetMousePress.bind(this));
+    }
+  },
+
+  /**
+   * Gets the element node or widget associated with this container.
+   * @return nsIDOMNode | object
+   */
+  get widget() {
+    return this._widget;
+  },
+
+  /**
+   * Prepares an item to be added to this container. This allows, for example,
+   * for a large number of items to be batched up before being sorted & added.
+   *
+   * If the "staged" flag is *not* set to true, the item will be immediately
+   * inserted at the correct position in this container, so that all the items
+   * still remain sorted. This can (possibly) be much slower than batching up
+   * multiple items.
+   *
+   * By default, this container assumes that all the items should be displayed
+   * sorted by their value. This can be overridden with the "index" flag,
+   * specifying on which position should an item be appended. The "staged" and
+   * "index" flags are mutually exclusive, meaning that all staged items
+   * will always be appended.
+   *
+   * @param nsIDOMNode element
+   *        A prebuilt node to be wrapped.
+   * @param string value
+   *        A string identifying the node.
+   * @param object options [optional]
+   *        Additional options or flags supported by this operation:
+   *          - attachment: some attached primitive/object for the item
+   *          - staged: true to stage the item to be appended later
+   *          - index: specifies on which position should the item be appended
+   *          - attributes: a batch of attributes set to the displayed element
+   *          - finalize: function invoked when the item is removed
+   * @return Item
+   *         The item associated with the displayed element if an unstaged push,
+   *         undefined if the item was staged for a later commit.
+   */
+  push: function ([element, value], options = {}) {
+    let item = new Item(this, element, value, options.attachment);
+
+    // Batch the item to be added later.
+    if (options.staged) {
+      // An ulterior commit operation will ignore any specified index, so
+      // no reason to keep it around.
+      options.index = undefined;
+      return void this._stagedItems.push({ item: item, options: options });
+    }
+    // Find the target position in this container and insert the item there.
+    if (!("index" in options)) {
+      return this._insertItemAt(this._findExpectedIndexFor(item), item,
+                                options);
+    }
+    // Insert the item at the specified index. If negative or out of bounds,
+    // the item will be simply appended.
+    return this._insertItemAt(options.index, item, options);
+  },
+
+  /**
+   * Flushes all the prepared items into this container.
+   * Any specified index on the items will be ignored. Everything is appended.
+   *
+   * @param object options [optional]
+   *        Additional options or flags supported by this operation:
+   *          - sorted: true to sort all the items before adding them
+   */
+  commit: function (options = {}) {
+    let stagedItems = this._stagedItems;
+
+    // Sort the items before adding them to this container, if preferred.
+    if (options.sorted) {
+      stagedItems.sort((a, b) => this._currentSortPredicate(a.item, b.item));
+    }
+    // Append the prepared items to this container.
+    for (let { item, opt } of stagedItems) {
+      this._insertItemAt(-1, item, opt);
+    }
+    // Recreate the temporary items list for ulterior pushes.
+    this._stagedItems.length = 0;
+  },
+
+  /**
+   * Immediately removes the specified item from this container.
+   *
+   * @param Item item
+   *        The item associated with the element to remove.
+   */
+  remove: function (item) {
+    if (!item) {
+      return;
+    }
+    this._widget.removeChild(item._target);
+    this._untangleItem(item);
+
+    if (!this._itemsByElement.size) {
+      this._preferredValue = this.selectedValue;
+      this._widget.selectedItem = null;
+      this._widget.setAttribute("emptyText", this._emptyText);
+    }
+  },
+
+  /**
+   * Removes the item at the specified index from this container.
+   *
+   * @param number index
+   *        The index of the item to remove.
+   */
+  removeAt: function (index) {
+    this.remove(this.getItemAtIndex(index));
+  },
+
+  /**
+   * Removes the items in this container based on a predicate.
+   */
+  removeForPredicate: function (predicate) {
+    let item;
+    while ((item = this.getItemForPredicate(predicate))) {
+      this.remove(item);
+    }
+  },
+
+  /**
+   * Removes all items from this container.
+   */
+  empty: function () {
+    this._preferredValue = this.selectedValue;
+    this._widget.selectedItem = null;
+    this._widget.removeAllItems();
+    this._widget.setAttribute("emptyText", this._emptyText);
+
+    for (let [, item] of this._itemsByElement) {
+      this._untangleItem(item);
+    }
+
+    this._itemsByValue.clear();
+    this._itemsByElement.clear();
+    this._stagedItems.length = 0;
+  },
+
+  /**
+   * Ensures the specified item is visible in this container.
+   *
+   * @param Item item
+   *        The item to bring into view.
+   */
+  ensureItemIsVisible: function (item) {
+    this._widget.ensureElementIsVisible(item._target);
+  },
+
+  /**
+   * Ensures the item at the specified index is visible in this container.
+   *
+   * @param number index
+   *        The index of the item to bring into view.
+   */
+  ensureIndexIsVisible: function (index) {
+    this.ensureItemIsVisible(this.getItemAtIndex(index));
+  },
+
+  /**
+   * Sugar for ensuring the selected item is visible in this container.
+   */
+  ensureSelectedItemIsVisible: function () {
+    this.ensureItemIsVisible(this.selectedItem);
+  },
+
+  /**
+   * If supported by the widget, the label string temporarily added to this
+   * container when there are no child items present.
+   */
+  set emptyText(value) {
+    this._emptyText = value;
+
+    // Apply the emptyText attribute right now if there are no child items.
+    if (!this._itemsByElement.size) {
+      this._widget.setAttribute("emptyText", value);
+    }
+  },
+
+  /**
+   * If supported by the widget, the label string permanently added to this
+   * container as a header.
+   * @param string value
+   */
+  set headerText(value) {
+    this._headerText = value;
+    this._widget.setAttribute("headerText", value);
+  },
+
+  /**
+   * Toggles all the items in this container hidden or visible.
+   *
+   * This does not change the default filtering predicate, so newly inserted
+   * items will always be visible. Use WidgetMethods.filterContents if you care.
+   *
+   * @param boolean visibleFlag
+   *        Specifies the intended visibility.
+   */
+  toggleContents: function (visibleFlag) {
+    for (let [element] of this._itemsByElement) {
+      element.hidden = !visibleFlag;
+    }
+  },
+
+  /**
+   * Toggles all items in this container hidden or visible based on a predicate.
+   *
+   * @param function predicate [optional]
+   *        Items are toggled according to the return value of this function,
+   *        which will become the new default filtering predicate in this
+   *        container.
+   *        If unspecified, all items will be toggled visible.
+   */
+  filterContents: function (predicate = this._currentFilterPredicate) {
+    this._currentFilterPredicate = predicate;
+
+    for (let [element, item] of this._itemsByElement) {
+      element.hidden = !predicate(item);
+    }
+  },
+
+  /**
+   * Sorts all the items in this container based on a predicate.
+   *
+   * @param function predicate [optional]
+   *        Items are sorted according to the return value of the function,
+   *        which will become the new default sorting predicate in this
+   *        container. If unspecified, all items will be sorted by their value.
+   */
+  sortContents: function (predicate = this._currentSortPredicate) {
+    let sortedItems = this.items.sort(this._currentSortPredicate = predicate);
+
+    for (let i = 0, len = sortedItems.length; i < len; i++) {
+      this.swapItems(this.getItemAtIndex(i), sortedItems[i]);
+    }
+  },
+
+  /**
+   * Visually swaps two items in this container.
+   *
+   * @param Item first
+   *        The first item to be swapped.
+   * @param Item second
+   *        The second item to be swapped.
+   */
+  swapItems: function (first, second) {
+    if (first == second) {
+      // We're just dandy, thank you.
+      return;
+    }
+    let { _prebuiltNode: firstPrebuiltTarget, _target: firstTarget } = first;
+    let { _prebuiltNode: secondPrebuiltTarget, _target: secondTarget } = second;
+
+    // If the two items were constructed with prebuilt nodes as
+    // DocumentFragments, then those DocumentFragments are now
+    // empty and need to be reassembled.
+    if (firstPrebuiltTarget instanceof DocumentFragment) {
+      for (let node of firstTarget.childNodes) {
+        firstPrebuiltTarget.appendChild(node.cloneNode(true));
+      }
+    }
+    if (secondPrebuiltTarget instanceof DocumentFragment) {
+      for (let node of secondTarget.childNodes) {
+        secondPrebuiltTarget.appendChild(node.cloneNode(true));
+      }
+    }
+
+    // 1. Get the indices of the two items to swap.
+    let i = this._indexOfElement(firstTarget);
+    let j = this._indexOfElement(secondTarget);
+
+    // 2. Remeber the selection index, to reselect an item, if necessary.
+    let selectedTarget = this._widget.selectedItem;
+    let selectedIndex = -1;
+    if (selectedTarget == firstTarget) {
+      selectedIndex = i;
+    } else if (selectedTarget == secondTarget) {
+      selectedIndex = j;
+    }
+
+    // 3. Silently nuke both items, nobody needs to know about this.
+    this._widget.removeChild(firstTarget);
+    this._widget.removeChild(secondTarget);
+    this._unlinkItem(first);
+    this._unlinkItem(second);
+
+    // 4. Add the items again, but reversing their indices.
+    this._insertItemAt.apply(this, i < j ? [i, second] : [j, first]);
+    this._insertItemAt.apply(this, i < j ? [j, first] : [i, second]);
+
+    // 5. Restore the previous selection, if necessary.
+    if (selectedIndex == i) {
+      this._widget.selectedItem = first._target;
+    } else if (selectedIndex == j) {
+      this._widget.selectedItem = second._target;
+    }
+
+    // 6. Let the outside world know that these two items were swapped.
+    ViewHelpers.dispatchEvent(first.target, "swap", [second, first]);
+  },
+
+  /**
+   * Visually swaps two items in this container at specific indices.
+   *
+   * @param number first
+   *        The index of the first item to be swapped.
+   * @param number second
+   *        The index of the second item to be swapped.
+   */
+  swapItemsAtIndices: function (first, second) {
+    this.swapItems(this.getItemAtIndex(first), this.getItemAtIndex(second));
+  },
+
+  /**
+   * Checks whether an item with the specified value is among the elements
+   * shown in this container.
+   *
+   * @param string value
+   *        The item's value.
+   * @return boolean
+   *         True if the value is known, false otherwise.
+   */
+  containsValue: function (value) {
+    return this._itemsByValue.has(value) ||
+           this._stagedItems.some(({ item }) => item._value == value);
+  },
+
+  /**
+   * Gets the "preferred value". This is the latest selected item's value,
+   * remembered just before emptying this container.
+   * @return string
+   */
+  get preferredValue() {
+    return this._preferredValue;
+  },
+
+  /**
+   * Retrieves the item associated with the selected element.
+   * @return Item | null
+   */
+  get selectedItem() {
+    let selectedElement = this._widget.selectedItem;
+    if (selectedElement) {
+      return this._itemsByElement.get(selectedElement);
+    }
+    return null;
+  },
+
+  /**
+   * Retrieves the selected element's index in this container.
+   * @return number
+   */
+  get selectedIndex() {
+    let selectedElement = this._widget.selectedItem;
+    if (selectedElement) {
+      return this._indexOfElement(selectedElement);
+    }
+    return -1;
+  },
+
+  /**
+   * Retrieves the value of the selected element.
+   * @return string
+   */
+  get selectedValue() {
+    let selectedElement = this._widget.selectedItem;
+    if (selectedElement) {
+      return this._itemsByElement.get(selectedElement)._value;
+    }
+    return "";
+  },
+
+  /**
+   * Retrieves the attachment of the selected element.
+   * @return object | null
+   */
+  get selectedAttachment() {
+    let selectedElement = this._widget.selectedItem;
+    if (selectedElement) {
+      return this._itemsByElement.get(selectedElement).attachment;
+    }
+    return null;
+  },
+
+  _selectItem: function (item) {
+    // A falsy item is allowed to invalidate the current selection.
+    let targetElement = item ? item._target : null;
+    let prevElement = this._widget.selectedItem;
+
+    // Make sure the selected item's target element is focused and visible.
+    if (this.autoFocusOnSelection && targetElement) {
+      targetElement.focus();
+    }
+
+    if (targetElement != prevElement) {
+      this._widget.selectedItem = targetElement;
+    }
+  },
+
+  /**
+   * Selects the element with the entangled item in this container.
+   * @param Item | function item
+   */
+  set selectedItem(item) {
+    // A predicate is allowed to select a specific item.
+    // If no item is matched, then the current selection is removed.
+    if (typeof item == "function") {
+      item = this.getItemForPredicate(item);
+    }
+
+    let targetElement = item ? item._target : null;
+    let prevElement = this._widget.selectedItem;
+
+    if (this.maintainSelectionVisible && targetElement) {
+      // Some methods are optional. See the WidgetMethods object documentation
+      // for a comprehensive list.
+      if ("ensureElementIsVisible" in this._widget) {
+        this._widget.ensureElementIsVisible(targetElement);
+      }
+    }
+
+    this._selectItem(item);
+
+    // Prevent selecting the same item again and avoid dispatching
+    // a redundant selection event, so return early.
+    if (targetElement != prevElement) {
+      let dispTarget = targetElement || prevElement;
+      let dispName = this.suppressSelectionEvents ? "suppressed-select"
+                                                  : "select";
+      ViewHelpers.dispatchEvent(dispTarget, dispName, item);
+    }
+  },
+
+  /**
+   * Selects the element at the specified index in this container.
+   * @param number index
+   */
+  set selectedIndex(index) {
+    let targetElement = this._widget.getItemAtIndex(index);
+    if (targetElement) {
+      this.selectedItem = this._itemsByElement.get(targetElement);
+      return;
+    }
+    this.selectedItem = null;
+  },
+
+  /**
+   * Selects the element with the specified value in this container.
+   * @param string value
+   */
+  set selectedValue(value) {
+    this.selectedItem = this._itemsByValue.get(value);
+  },
+
+  /**
+   * Deselects and re-selects an item in this container.
+   *
+   * Useful when you want a "select" event to be emitted, even though
+   * the specified item was already selected.
+   *
+   * @param Item | function item
+   * @see `set selectedItem`
+   */
+  forceSelect: function (item) {
+    this.selectedItem = null;
+    this.selectedItem = item;
+  },
+
+  /**
+   * Specifies if this container should try to keep the selected item visible.
+   * (For example, when new items are added the selection is brought into view).
+   */
+  maintainSelectionVisible: true,
+
+  /**
+   * Specifies if "select" events dispatched from the elements in this container
+   * when their respective items are selected should be suppressed or not.
+   *
+   * If this flag is set to true, then consumers of this container won't
+   * be normally notified when items are selected.
+   */
+  suppressSelectionEvents: false,
+
+  /**
+   * Focus this container the first time an element is inserted?
+   *
+   * If this flag is set to true, then when the first item is inserted in
+   * this container (and thus it's the only item available), its corresponding
+   * target element is focused as well.
+   */
+  autoFocusOnFirstItem: true,
+
+  /**
+   * Focus on selection?
+   *
+   * If this flag is set to true, then whenever an item is selected in
+   * this container (e.g. via the selectedIndex or selectedItem setters),
+   * its corresponding target element is focused as well.
+   *
+   * You can disable this flag, for example, to maintain a certain node
+   * focused but visually indicate a different selection in this container.
+   */
+  autoFocusOnSelection: true,
+
+  /**
+   * Focus on input (e.g. mouse click)?
+   *
+   * If this flag is set to true, then whenever an item receives user input in
+   * this container, its corresponding target element is focused as well.
+   */
+  autoFocusOnInput: true,
+
+  /**
+   * When focusing on input, allow right clicks?
+   * @see WidgetMethods.autoFocusOnInput
+   */
+  allowFocusOnRightClick: false,
+
+  /**
+   * The number of elements in this container to jump when Page Up or Page Down
+   * keys are pressed. If falsy, then the page size will be based on the
+   * number of visible items in the container.
+   */
+  pageSize: 0,
+
+  /**
+   * Focuses the first visible item in this container.
+   */
+  focusFirstVisibleItem: function () {
+    this.focusItemAtDelta(-this.itemCount);
+  },
+
+  /**
+   * Focuses the last visible item in this container.
+   */
+  focusLastVisibleItem: function () {
+    this.focusItemAtDelta(+this.itemCount);
+  },
+
+  /**
+   * Focuses the next item in this container.
+   */
+  focusNextItem: function () {
+    this.focusItemAtDelta(+1);
+  },
+
+  /**
+   * Focuses the previous item in this container.
+   */
+  focusPrevItem: function () {
+    this.focusItemAtDelta(-1);
+  },
+
+  /**
+   * Focuses another item in this container based on the index distance
+   * from the currently focused item.
+   *
+   * @param number delta
+   *        A scalar specifying by how many items should the selection change.
+   */
+  focusItemAtDelta: function (delta) {
+    // Make sure the currently selected item is also focused, so that the
+    // command dispatcher mechanism has a relative node to work with.
+    // If there's no selection, just select an item at a corresponding index
+    // (e.g. the first item in this container if delta <= 1).
+    let selectedElement = this._widget.selectedItem;
+    if (selectedElement) {
+      selectedElement.focus();
+    } else {
+      this.selectedIndex = Math.max(0, delta - 1);
+      return;
+    }
+
+    let direction = delta > 0 ? "advanceFocus" : "rewindFocus";
+    let distance = Math.abs(Math[delta > 0 ? "ceil" : "floor"](delta));
+    while (distance--) {
+      if (!this._focusChange(direction)) {
+        // Out of bounds.
+        break;
+      }
+    }
+
+    // Synchronize the selected item as being the currently focused element.
+    this.selectedItem = this.getItemForElement(this._focusedElement);
+  },
+
+  /**
+   * Focuses the next or previous item in this container.
+   *
+   * @param string direction
+   *        Either "advanceFocus" or "rewindFocus".
+   * @return boolean
+   *         False if the focus went out of bounds and the first or last item
+   *         in this container was focused instead.
+   */
+  _focusChange: function (direction) {
+    let commandDispatcher = this._commandDispatcher;
+    let prevFocusedElement = commandDispatcher.focusedElement;
+    let currFocusedElement;
+
+    do {
+      commandDispatcher.suppressFocusScroll = true;
+      commandDispatcher[direction]();
+      currFocusedElement = commandDispatcher.focusedElement;
+
+      // Make sure the newly focused item is a part of this container. If the
+      // focus goes out of bounds, revert the previously focused item.
+      if (!this.getItemForElement(currFocusedElement)) {
+        prevFocusedElement.focus();
+        return false;
+      }
+    } while (!WIDGET_FOCUSABLE_NODES.has(currFocusedElement.tagName));
+
+    // Focus remained within bounds.
+    return true;
+  },
+
+  /**
+   * Gets the command dispatcher instance associated with this container's DOM.
+   * If there are no items displayed in this container, null is returned.
+   * @return nsIDOMXULCommandDispatcher | null
+   */
+  get _commandDispatcher() {
+    if (this._cachedCommandDispatcher) {
+      return this._cachedCommandDispatcher;
+    }
+    let someElement = this._widget.getItemAtIndex(0);
+    if (someElement) {
+      let commandDispatcher = someElement.ownerDocument.commandDispatcher;
+      this._cachedCommandDispatcher = commandDispatcher;
+      return commandDispatcher;
+    }
+    return null;
+  },
+
+  /**
+   * Gets the currently focused element in this container.
+   *
+   * @return nsIDOMNode
+   *         The focused element, or null if nothing is found.
+   */
+  get _focusedElement() {
+    let commandDispatcher = this._commandDispatcher;
+    if (commandDispatcher) {
+      return commandDispatcher.focusedElement;
+    }
+    return null;
+  },
+
+  /**
+   * Gets the item in the container having the specified index.
+   *
+   * @param number index
+   *        The index used to identify the element.
+   * @return Item
+   *         The matched item, or null if nothing is found.
+   */
+  getItemAtIndex: function (index) {
+    return this.getItemForElement(this._widget.getItemAtIndex(index));
+  },
+
+  /**
+   * Gets the item in the container having the specified value.
+   *
+   * @param string value
+   *        The value used to identify the element.
+   * @return Item
+   *         The matched item, or null if nothing is found.
+   */
+  getItemByValue: function (value) {
+    return this._itemsByValue.get(value);
+  },
+
+  /**
+   * Gets the item in the container associated with the specified element.
+   *
+   * @param nsIDOMNode element
+   *        The element used to identify the item.
+   * @param object flags [optional]
+   *        Additional options for showing the source. Supported options:
+   *          - noSiblings: if siblings shouldn't be taken into consideration
+   *                        when searching for the associated item.
+   * @return Item
+   *         The matched item, or null if nothing is found.
+   */
+  getItemForElement: function (element, flags = {}) {
+    while (element) {
+      let item = this._itemsByElement.get(element);
+
+      // Also search the siblings if allowed.
+      if (!flags.noSiblings) {
+        item = item ||
+          this._itemsByElement.get(element.nextElementSibling) ||
+          this._itemsByElement.get(element.previousElementSibling);
+      }
+      if (item) {
+        return item;
+      }
+      element = element.parentNode;
+    }
+    return null;
+  },
+
+  /**
+   * Gets a visible item in this container validating a specified predicate.
+   *
+   * @param function predicate
+   *        The first item which validates this predicate is returned
+   * @return Item
+   *         The matched item, or null if nothing is found.
+   */
+  getItemForPredicate: function (predicate, owner = this) {
+    // Recursively check the items in this widget for a predicate match.
+    for (let [element, item] of owner._itemsByElement) {
+      let match;
+      if (predicate(item) && !element.hidden) {
+        match = item;
+      } else {
+        match = this.getItemForPredicate(predicate, item);
+      }
+      if (match) {
+        return match;
+      }
+    }
+    // Also check the staged items. No need to do this recursively since
+    // they're not even appended to the view yet.
+    for (let { item } of this._stagedItems) {
+      if (predicate(item)) {
+        return item;
+      }
+    }
+    return null;
+  },
+
+  /**
+   * Shortcut function for getItemForPredicate which works on item attachments.
+   * @see getItemForPredicate
+   */
+  getItemForAttachment: function (predicate, owner = this) {
+    return this.getItemForPredicate(e => predicate(e.attachment));
+  },
+
+  /**
+   * Finds the index of an item in the container.
+   *
+   * @param Item item
+   *        The item get the index for.
+   * @return number
+   *         The index of the matched item, or -1 if nothing is found.
+   */
+  indexOfItem: function (item) {
+    return this._indexOfElement(item._target);
+  },
+
+  /**
+   * Finds the index of an element in the container.
+   *
+   * @param nsIDOMNode element
+   *        The element get the index for.
+   * @return number
+   *         The index of the matched element, or -1 if nothing is found.
+   */
+  _indexOfElement: function (element) {
+    for (let i = 0; i < this._itemsByElement.size; i++) {
+      if (this._widget.getItemAtIndex(i) == element) {
+        return i;
+      }
+    }
+    return -1;
+  },
+
+  /**
+   * Gets the total number of items in this container.
+   * @return number
+   */
+  get itemCount() {
+    return this._itemsByElement.size;
+  },
+
+  /**
+   * Returns a list of items in this container, in the displayed order.
+   * @return array
+   */
+  get items() {
+    let store = [];
+    let itemCount = this.itemCount;
+    for (let i = 0; i < itemCount; i++) {
+      store.push(this.getItemAtIndex(i));
+    }
+    return store;
+  },
+
+  /**
+   * Returns a list of values in this container, in the displayed order.
+   * @return array
+   */
+  get values() {
+    return this.items.map(e => e._value);
+  },
+
+  /**
+   * Returns a list of attachments in this container, in the displayed order.
+   * @return array
+   */
+  get attachments() {
+    return this.items.map(e => e.attachment);
+  },
+
+  /**
+   * Returns a list of all the visible (non-hidden) items in this container,
+   * in the displayed order
+   * @return array
+   */
+  get visibleItems() {
+    return this.items.filter(e => !e._target.hidden);
+  },
+
+  /**
+   * Checks if an item is unique in this container. If an item's value is an
+   * empty string, "undefined" or "null", it is considered unique.
+   *
+   * @param Item item
+   *        The item for which to verify uniqueness.
+   * @return boolean
+   *         True if the item is unique, false otherwise.
+   */
+  isUnique: function (item) {
+    let value = item._value;
+    if (value == "" || value == "undefined" || value == "null") {
+      return true;
+    }
+    return !this._itemsByValue.has(value);
+  },
+
+  /**
+   * Checks if an item is eligible for this container. By default, this checks
+   * whether an item is unique and has a prebuilt target node.
+   *
+   * @param Item item
+   *        The item for which to verify eligibility.
+   * @return boolean
+   *         True if the item is eligible, false otherwise.
+   */
+  isEligible: function (item) {
+    return this.isUnique(item) && item._prebuiltNode;
+  },
+
+  /**
+   * Finds the expected item index in this container based on the default
+   * sort predicate.
+   *
+   * @param Item item
+   *        The item for which to get the expected index.
+   * @return number
+   *         The expected item index.
+   */
+  _findExpectedIndexFor: function (item) {
+    let itemCount = this.itemCount;
+    for (let i = 0; i < itemCount; i++) {
+      if (this._currentSortPredicate(this.getItemAtIndex(i), item) > 0) {
+        return i;
+      }
+    }
+    return itemCount;
+  },
+
+  /**
+   * Immediately inserts an item in this container at the specified index.
+   *
+   * @param number index
+   *        The position in the container intended for this item.
+   * @param Item item
+   *        The item describing a target element.
+   * @param object options [optional]
+   *        Additional options or flags supported by this operation:
+   *          - attributes: a batch of attributes set to the displayed element
+   *          - finalize: function when the item is untangled (removed)
+   * @return Item
+   *         The item associated with the displayed element, null if rejected.
+   */
+  _insertItemAt: function (index, item, options = {}) {
+    if (!this.isEligible(item)) {
+      return null;
+    }
+
+    // Entangle the item with the newly inserted node.
+    // Make sure this is done with the value returned by insertItemAt(),
+    // to avoid storing a potential DocumentFragment.
+    let node = item._prebuiltNode;
+    let attachment = item.attachment;
+    this._entangleItem(item,
+                       this._widget.insertItemAt(index, node, attachment));
+
+    // Handle any additional options after entangling the item.
+    if (!this._currentFilterPredicate(item)) {
+      item._target.hidden = true;
+    }
+    if (this.autoFocusOnFirstItem && this._itemsByElement.size == 1) {
+      item._target.focus();
+    }
+    if (options.attributes) {
+      options.attributes.forEach(e => item._target.setAttribute(e[0], e[1]));
+    }
+    if (options.finalize) {
+      item.finalize = options.finalize;
+    }
+
+    // Hide the empty text if the selection wasn't lost.
+    this._widget.removeAttribute("emptyText");
+
+    // Return the item associated with the displayed element.
+    return item;
+  },
+
+  /**
+   * Entangles an item (model) with a displayed node element (view).
+   *
+   * @param Item item
+   *        The item describing a target element.
+   * @param nsIDOMNode element
+   *        The element displaying the item.
+   */
+  _entangleItem: function (item, element) {
+    this._itemsByValue.set(item._value, item);
+    this._itemsByElement.set(element, item);
+    item._target = element;
+  },
+
+  /**
+   * Untangles an item (model) from a displayed node element (view).
+   *
+   * @param Item item
+   *        The item describing a target element.
+   */
+  _untangleItem: function (item) {
+    if (item.finalize) {
+      item.finalize(item);
+    }
+    for (let childItem of item) {
+      item.remove(childItem);
+    }
+
+    this._unlinkItem(item);
+    item._target = null;
+  },
+
+  /**
+   * Deletes an item from the its parent's storage maps.
+   *
+   * @param Item item
+   *        The item describing a target element.
+   */
+  _unlinkItem: function (item) {
+    this._itemsByValue.delete(item._value);
+    this._itemsByElement.delete(item._target);
+  },
+
+  /**
+   * The keyPress event listener for this container.
+   * @param string name
+   * @param KeyboardEvent event
+   */
+  _onWidgetKeyPress: function (name, event) {
+    // Prevent scrolling when pressing navigation keys.
+    ViewHelpers.preventScrolling(event);
+
+    switch (event.keyCode) {
+      case KeyCodes.DOM_VK_UP:
+      case KeyCodes.DOM_VK_LEFT:
+        this.focusPrevItem();
+        return;
+      case KeyCodes.DOM_VK_DOWN:
+      case KeyCodes.DOM_VK_RIGHT:
+        this.focusNextItem();
+        return;
+      case KeyCodes.DOM_VK_PAGE_UP:
+        this.focusItemAtDelta(-(this.pageSize ||
+                               (this.itemCount / PAGE_SIZE_ITEM_COUNT_RATIO)));
+        return;
+      case KeyCodes.DOM_VK_PAGE_DOWN:
+        this.focusItemAtDelta(+(this.pageSize ||
+                               (this.itemCount / PAGE_SIZE_ITEM_COUNT_RATIO)));
+        return;
+      case KeyCodes.DOM_VK_HOME:
+        this.focusFirstVisibleItem();
+        return;
+      case KeyCodes.DOM_VK_END:
+        this.focusLastVisibleItem();
+        return;
+    }
+  },
+
+  /**
+   * The mousePress event listener for this container.
+   * @param string name
+   * @param MouseEvent event
+   */
+  _onWidgetMousePress: function (name, event) {
+    if (event.button != 0 && !this.allowFocusOnRightClick) {
+      // Only allow left-click to trigger this event.
+      return;
+    }
+
+    let item = this.getItemForElement(event.target);
+    if (item) {
+      // The container is not empty and we clicked on an actual item.
+      this.selectedItem = item;
+      // Make sure the current event's target element is also focused.
+      this.autoFocusOnInput && item._target.focus();
+    }
+  },
+
+  /**
+   * The predicate used when filtering items. By default, all items in this
+   * view are visible.
+   *
+   * @param Item item
+   *        The item passing through the filter.
+   * @return boolean
+   *         True if the item should be visible, false otherwise.
+   */
+  _currentFilterPredicate: function (item) {
+    return true;
+  },
+
+  /**
+   * The predicate used when sorting items. By default, items in this view
+   * are sorted by their label.
+   *
+   * @param Item first
+   *        The first item used in the comparison.
+   * @param Item second
+   *        The second item used in the comparison.
+   * @return number
+   *         -1 to sort first to a lower index than second
+   *          0 to leave first and second unchanged with respect to each other
+   *          1 to sort second to a lower index than first
+   */
+  _currentSortPredicate: function (first, second) {
+    return +(first._value.toLowerCase() > second._value.toLowerCase());
+  },
+
+  /**
+   * Call a method on this widget named `methodName`. Any further arguments are
+   * passed on to the method. Returns the result of the method call.
+   *
+   * @param String methodName
+   *        The name of the method you want to call.
+   * @param args
+   *        Optional. Any arguments you want to pass through to the method.
+   */
+  callMethod: function (methodName, ...args) {
+    return this._widget[methodName].apply(this._widget, args);
+  },
+
+  _widget: null,
+  _emptyText: "",
+  _headerText: "",
+  _preferredValue: "",
+  _cachedCommandDispatcher: null
+};
+
+/**
+ * A generator-iterator over all the items in this container.
+ */
+Item.prototype[Symbol.iterator] =
+WidgetMethods[Symbol.iterator] = function* () {
+  yield* this._itemsByElement.values();
+};