Adding upstream version 110.0.1.upstream/110.0.1upstream

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

1 files changed, 637 insertions, 0 deletions

diff --git a/toolkit/content/widgets/spinner.js b/toolkit/content/widgets/spinner.js
new file mode 100644
index 0000000000..2adefc7392
--- /dev/null
+++ b/toolkit/content/widgets/spinner.js
@@ -0,0 +1,637 @@
+/* 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";
+
+/*
+ * The spinner is responsible for displaying the items, and does
+ * not care what the values represent. The setValue function is called
+ * when it detects a change in value triggered by scroll event.
+ * Supports scrolling, clicking on up or down, clicking on item, and
+ * dragging.
+ */
+
+function Spinner(props, context) {
+  this.context = context;
+  this._init(props);
+}
+
+{
+  const ITEM_HEIGHT = 2.5,
+    VIEWPORT_SIZE = 7,
+    VIEWPORT_COUNT = 5;
+
+  Spinner.prototype = {
+    /**
+     * Initializes a spinner. Set the default states and properties, cache
+     * element references, create the HTML markup, and add event listeners.
+     *
+     * @param  {Object} props [Properties passed in from parent]
+     *         {
+     *           {Function} setValue: Takes a value and set the state to
+     *             the parent component.
+     *           {Function} getDisplayString: Takes a value, and output it
+     *             as localized strings.
+     *           {Number} viewportSize [optional]: Number of items in a
+     *             viewport.
+     *           {Boolean} hideButtons [optional]: Hide up & down buttons
+     *           {Number} rootFontSize [optional]: Used to support zoom in/out
+     *         }
+     */
+    _init(props) {
+      const {
+        id,
+        setValue,
+        getDisplayString,
+        hideButtons,
+        rootFontSize = 10,
+      } = props;
+
+      const spinnerTemplate = document.getElementById("spinner-template");
+      const spinnerElement = document.importNode(spinnerTemplate.content, true);
+
+      // Make sure viewportSize is an odd number because we want to have the selected
+      // item in the center. If it's an even number, use the default size instead.
+      const viewportSize =
+        props.viewportSize % 2 ? props.viewportSize : VIEWPORT_SIZE;
+
+      this.state = {
+        items: [],
+        isScrolling: false,
+      };
+      this.props = {
+        setValue,
+        getDisplayString,
+        viewportSize,
+        rootFontSize,
+        // We can assume that the viewportSize is an odd number. Calculate how many
+        // items we need to insert on top of the spinner so that the selected is at
+        // the center. Ex: if viewportSize is 5, we need 2 items on top.
+        viewportTopOffset: (viewportSize - 1) / 2,
+      };
+      this.elements = {
+        container: spinnerElement.querySelector(".spinner-container"),
+        spinner: spinnerElement.querySelector(".spinner"),
+        up: spinnerElement.querySelector(".up"),
+        down: spinnerElement.querySelector(".down"),
+        itemsViewElements: [],
+      };
+
+      this.elements.spinner.style.height = ITEM_HEIGHT * viewportSize + "rem";
+
+      // Prepares the spinner container to function as a spinbutton and expose
+      // its properties to assistive technology
+      this.elements.spinner.setAttribute("role", "spinbutton");
+      this.elements.spinner.setAttribute("tabindex", "0");
+      // Remove up/down buttons from the focus order, because a keyboard-only
+      // user can adjust values by pressing Up/Down arrow keys on a spinbutton,
+      // otherwise it creates extra, redundant tab order stops for users
+      this.elements.up.setAttribute("tabindex", "-1");
+      this.elements.down.setAttribute("tabindex", "-1");
+
+      if (id) {
+        this.elements.container.id = id;
+      }
+      if (hideButtons) {
+        this.elements.container.classList.add("hide-buttons");
+      }
+
+      this.context.appendChild(spinnerElement);
+      this._attachEventListeners();
+    },
+
+    /**
+     * Only the parent component calls setState on the spinner.
+     * It checks if the items have changed and updates the spinner.
+     * If only the value has changed, smooth scrolls to the new value.
+     *
+     * @param {Object} newState [The new spinner state]
+     *        {
+     *          {Number/String} value: The centered value
+     *          {Array} items: The list of items for display
+     *          {Boolean} isInfiniteScroll: Whether or not the spinner should
+     *            have infinite scroll capability
+     *          {Boolean} isValueSet: true if user has selected a value
+     *        }
+     */
+    setState(newState) {
+      const { value, items } = this.state;
+      const {
+        value: newValue,
+        items: newItems,
+        isValueSet,
+        isInvalid,
+        smoothScroll = true,
+      } = newState;
+
+      if (this._isArrayDiff(newItems, items)) {
+        this.state = Object.assign(this.state, newState);
+        this._updateItems();
+        this._scrollTo(newValue, /* centering = */ true, /* smooth = */ false);
+      } else if (newValue != value) {
+        this.state = Object.assign(this.state, newState);
+        this._scrollTo(newValue, /* centering = */ true, smoothScroll);
+      }
+
+      this.elements.spinner.setAttribute(
+        "aria-valuemin",
+        this.state.items[0].value
+      );
+      this.elements.spinner.setAttribute(
+        "aria-valuemax",
+        this.state.items.at(-1).value
+      );
+      this.elements.spinner.setAttribute("aria-valuenow", this.state.value);
+      if (!this.elements.spinner.getAttribute("aria-valuetext")) {
+        this.elements.spinner.setAttribute(
+          "aria-valuetext",
+          this.props.getDisplayString(this.state.value)
+        );
+      }
+
+      // Show selection even if it's passed down from the parent
+      if ((isValueSet && !isInvalid) || this.state.index) {
+        this._updateSelection();
+      } else {
+        this._removeSelection();
+      }
+    },
+
+    /**
+     * Whenever scroll event is detected:
+     * - Update the index state
+     * - If the value has changed, update the [value] state and call [setValue]
+     * - If infinite scrolling is on, reset the scrolling position if necessary
+     */
+    _onScroll() {
+      const { items, itemsView, isInfiniteScroll } = this.state;
+      const { viewportSize, viewportTopOffset } = this.props;
+      const { spinner } = this.elements;
+
+      this.state.index = this._getIndexByOffset(spinner.scrollTop);
+
+      const value = itemsView[this.state.index + viewportTopOffset].value;
+
+      // Call setValue if value has changed
+      if (this.state.value != value) {
+        this.state.value = value;
+        this.props.setValue(value);
+      }
+
+      // Do infinite scroll when items length is bigger or equal to viewport
+      // and isInfiniteScroll is not false.
+      if (items.length >= viewportSize && isInfiniteScroll) {
+        // If the scroll position is near the top or bottom, jump back to the middle
+        // so user can keep scrolling up or down.
+        if (
+          this.state.index < viewportSize ||
+          this.state.index > itemsView.length - viewportSize
+        ) {
+          this._scrollTo(this.state.value, true);
+        }
+      }
+
+      this.elements.spinner.classList.add("scrolling");
+    },
+
+    /**
+     * Remove the "scrolling" state on scrollend.
+     */
+    _onScrollend() {
+      this.elements.spinner.classList.remove("scrolling");
+      this.elements.spinner.setAttribute(
+        "aria-valuetext",
+        this.props.getDisplayString(this.state.value)
+      );
+    },
+
+    /**
+     * Updates the spinner items to the current states.
+     */
+    _updateItems() {
+      const { viewportSize, viewportTopOffset } = this.props;
+      const { items, isInfiniteScroll } = this.state;
+
+      // Prepends null elements so the selected value is centered in spinner
+      let itemsView = new Array(viewportTopOffset).fill({}).concat(items);
+
+      if (items.length >= viewportSize && isInfiniteScroll) {
+        // To achieve infinite scroll, we move the scroll position back to the
+        // center when it is near the top or bottom. The scroll momentum could
+        // be lost in the process, so to minimize that, we need at least 2 sets
+        // of items to act as buffer: one for the top and one for the bottom.
+        // But if the number of items is small ( < viewportSize * viewport count)
+        // we should add more sets.
+        let count =
+          Math.ceil((viewportSize * VIEWPORT_COUNT) / items.length) * 2;
+        for (let i = 0; i < count; i += 1) {
+          itemsView.push(...items);
+        }
+      }
+
+      // Reuse existing DOM nodes when possible. Create or remove
+      // nodes based on how big itemsView is.
+      this._prepareNodes(itemsView.length, this.elements.spinner);
+      // Once DOM nodes are ready, set display strings using textContent
+      this._setDisplayStringAndClass(
+        itemsView,
+        this.elements.itemsViewElements
+      );
+
+      this.state.itemsView = itemsView;
+    },
+
+    /**
+     * Make sure the number or child elements is the same as length
+     * and keep the elements' references for updating textContent
+     *
+     * @param {Number} length [The number of child elements]
+     * @param {DOMElement} parent [The parent element reference]
+     */
+    _prepareNodes(length, parent) {
+      const diff = length - parent.childElementCount;
+
+      if (!diff) {
+        return;
+      }
+
+      if (diff > 0) {
+        // Add more elements if length is greater than current
+        let frag = document.createDocumentFragment();
+
+        // Remove margin bottom on the last element before appending
+        if (parent.lastChild) {
+          parent.lastChild.style.marginBottom = "";
+        }
+
+        for (let i = 0; i < diff; i++) {
+          let el = document.createElement("div");
+          // Spinbutton elements should be hidden from assistive technology:
+          el.setAttribute("aria-hidden", "true");
+          frag.appendChild(el);
+          this.elements.itemsViewElements.push(el);
+        }
+        parent.appendChild(frag);
+      } else if (diff < 0) {
+        // Remove elements if length is less than current
+        for (let i = 0; i < Math.abs(diff); i++) {
+          parent.removeChild(parent.lastChild);
+        }
+        this.elements.itemsViewElements.splice(diff);
+      }
+
+      parent.lastChild.style.marginBottom =
+        ITEM_HEIGHT * this.props.viewportTopOffset + "rem";
+    },
+
+    /**
+     * Set the display string and class name to the elements.
+     *
+     * @param {Array<Object>} items
+     *        [{
+     *          {Number/String} value: The value in its original form
+     *          {Boolean} enabled: Whether or not the item is enabled
+     *        }]
+     * @param {Array<DOMElement>} elements
+     */
+    _setDisplayStringAndClass(items, elements) {
+      const { getDisplayString } = this.props;
+
+      items.forEach((item, index) => {
+        elements[index].textContent =
+          item.value != undefined ? getDisplayString(item.value) : "";
+        elements[index].className = item.enabled ? "" : "disabled";
+      });
+    },
+
+    /**
+     * Attach event listeners to the spinner and buttons.
+     */
+    _attachEventListeners() {
+      const { spinner, container } = this.elements;
+
+      spinner.addEventListener("scroll", this, { passive: true });
+      spinner.addEventListener("scrollend", this, { passive: true });
+      spinner.addEventListener("keydown", this);
+      container.addEventListener("mouseup", this, { passive: true });
+      container.addEventListener("mousedown", this, { passive: true });
+      container.addEventListener("keydown", this);
+    },
+
+    /**
+     * Handle events
+     * @param  {DOMEvent} event
+     */
+    handleEvent(event) {
+      const { mouseState = {}, index, itemsView } = this.state;
+      const { viewportTopOffset, setValue } = this.props;
+      const { spinner, up, down } = this.elements;
+
+      switch (event.type) {
+        case "scroll": {
+          this._onScroll();
+          break;
+        }
+        case "scrollend": {
+          this._onScrollend();
+          break;
+        }
+        case "mousedown": {
+          this.state.mouseState = {
+            down: true,
+            layerX: event.layerX,
+            layerY: event.layerY,
+          };
+          if (event.target == up) {
+            // An "active" class is needed to simulate :active pseudo-class
+            // because element is not focused.
+            event.target.classList.add("active");
+            this._smoothScrollToIndex(index - 1);
+          }
+          if (event.target == down) {
+            event.target.classList.add("active");
+            this._smoothScrollToIndex(index + 1);
+          }
+          if (event.target.parentNode == spinner) {
+            // Listen to dragging events
+            spinner.addEventListener("mousemove", this, { passive: true });
+            spinner.addEventListener("mouseleave", this, { passive: true });
+          }
+          break;
+        }
+        case "mouseup": {
+          this.state.mouseState.down = false;
+          if (event.target == up || event.target == down) {
+            event.target.classList.remove("active");
+          }
+          if (event.target.parentNode == spinner) {
+            // Check if user clicks or drags, scroll to the item if clicked,
+            // otherwise get the current index and smooth scroll there.
+            if (
+              event.layerX == mouseState.layerX &&
+              event.layerY == mouseState.layerY
+            ) {
+              const newIndex =
+                this._getIndexByOffset(event.target.offsetTop) -
+                viewportTopOffset;
+              if (index == newIndex) {
+                // Set value manually if the clicked element is already centered.
+                // This happens when the picker first opens, and user pick the
+                // default value.
+                setValue(itemsView[index + viewportTopOffset].value);
+              } else {
+                this._smoothScrollToIndex(newIndex);
+              }
+            } else {
+              this._smoothScrollToIndex(
+                this._getIndexByOffset(spinner.scrollTop)
+              );
+            }
+            // Stop listening to dragging
+            spinner.removeEventListener("mousemove", this, { passive: true });
+            spinner.removeEventListener("mouseleave", this, { passive: true });
+          }
+          break;
+        }
+        case "mouseleave": {
+          if (event.target == spinner) {
+            // Stop listening to drag event if mouse is out of the spinner
+            this._smoothScrollToIndex(
+              this._getIndexByOffset(spinner.scrollTop)
+            );
+            spinner.removeEventListener("mousemove", this, { passive: true });
+            spinner.removeEventListener("mouseleave", this, { passive: true });
+          }
+          break;
+        }
+        case "mousemove": {
+          // Change spinner position on drag
+          spinner.scrollTop -= event.movementY;
+          break;
+        }
+        case "keydown": {
+          // Providing keyboard navigation support in accordance with
+          // the ARIA Spinbutton design pattern
+          if (event.target === spinner) {
+            switch (event.key) {
+              case "ArrowUp": {
+                // While the spinner is focused, selects previous value and centers it
+                this._setValueForSpinner(event, index - 1);
+                break;
+              }
+              case "ArrowDown": {
+                // While the spinner is focused, selects next value and centers it
+                this._setValueForSpinner(event, index + 1);
+                break;
+              }
+              case "PageUp": {
+                // While the spinner is focused, selects 5th value above and centers it
+                this._setValueForSpinner(event, index - 5);
+                break;
+              }
+              case "PageDown": {
+                // While the spinner is focused, selects 5th value below and centers it
+                this._setValueForSpinner(event, index + 5);
+                break;
+              }
+              case "Home": {
+                // While the spinner is focused, selects the min value and centers it
+                let targetValue;
+                for (let i = 0; i < this.state.items.length - 1; i++) {
+                  if (this.state.items[i].enabled) {
+                    targetValue = this.state.items[i].value;
+                    break;
+                  }
+                }
+                this._smoothScrollTo(targetValue);
+                event.stopPropagation();
+                event.preventDefault();
+                break;
+              }
+              case "End": {
+                // While the spinner is focused, selects the max value and centers it
+                let targetValue;
+                for (let i = this.state.items.length - 1; i >= 0; i--) {
+                  if (this.state.items[i].enabled) {
+                    targetValue = this.state.items[i].value;
+                    break;
+                  }
+                }
+                this._smoothScrollTo(targetValue);
+                event.stopPropagation();
+                event.preventDefault();
+                break;
+              }
+            }
+          }
+        }
+      }
+    },
+
+    /**
+     * Find the index by offset
+     * @param {Number} offset: Offset value in pixel.
+     * @return {Number}  Index number
+     */
+    _getIndexByOffset(offset) {
+      return Math.round(offset / (ITEM_HEIGHT * this.props.rootFontSize));
+    },
+
+    /**
+     * Find the index of a value that is the closest to the current position.
+     * If centering is true, find the index closest to the center.
+     *
+     * @param {Number/String} value: The value to find
+     * @param {Boolean} centering: Whether or not to find the value closest to center
+     * @return {Number} index of the value, returns -1 if value is not found
+     */
+    _getScrollIndex(value, centering) {
+      const { itemsView } = this.state;
+      const { viewportTopOffset } = this.props;
+
+      // If index doesn't exist, or centering is true, start from the middle point
+      let currentIndex =
+        centering || this.state.index == undefined
+          ? Math.round((itemsView.length - viewportTopOffset) / 2)
+          : this.state.index;
+      let closestIndex = itemsView.length;
+      let indexes = [];
+      let diff = closestIndex;
+      let isValueFound = false;
+
+      // Find indexes of items match the value
+      itemsView.forEach((item, index) => {
+        if (item.value == value) {
+          indexes.push(index);
+        }
+      });
+
+      // Find the index closest to currentIndex
+      indexes.forEach(index => {
+        let d = Math.abs(index - currentIndex);
+        if (d < diff) {
+          diff = d;
+          closestIndex = index;
+          isValueFound = true;
+        }
+      });
+
+      return isValueFound ? closestIndex - viewportTopOffset : -1;
+    },
+
+    /**
+     * Scroll to a value based on the index
+     *
+     * @param  {Number} index: Index number
+     * @param  {Boolean} smooth: Whether or not scroll should be smooth by default
+     */
+    _scrollToIndex(index, smooth) {
+      // Do nothing if the value is not found
+      if (index < 0) {
+        return;
+      }
+      this.state.index = index;
+      const element = this.elements.spinner.children[index];
+      if (!element) {
+        return;
+      }
+      element.scrollIntoView({
+        behavior: smooth ? "auto" : "instant",
+        block: "start",
+      });
+    },
+
+    /**
+     * Scroll to a value.
+     *
+     * @param  {Number/String} value: Value to scroll to
+     * @param  {Boolean} centering: Whether or not to scroll to center location
+     * @param  {Boolean} smooth: Whether or not scroll should be smooth by default
+     */
+    _scrollTo(value, centering, smooth) {
+      const index = this._getScrollIndex(value, centering);
+      this._scrollToIndex(index, smooth);
+    },
+
+    _smoothScrollTo(value) {
+      this._scrollTo(value, /* centering = */ false, /* smooth = */ true);
+    },
+
+    _smoothScrollToIndex(index) {
+      this._scrollToIndex(index, /* smooth = */ true);
+    },
+
+    /**
+     * Update the selection state.
+     */
+    _updateSelection() {
+      const { itemsViewElements, selected } = this.elements;
+      const { itemsView, index } = this.state;
+      const { viewportTopOffset } = this.props;
+      const currentItemIndex = index + viewportTopOffset;
+
+      if (selected && selected != itemsViewElements[currentItemIndex]) {
+        this._removeSelection();
+      }
+
+      this.elements.selected = itemsViewElements[currentItemIndex];
+      if (itemsView[currentItemIndex] && itemsView[currentItemIndex].enabled) {
+        this.elements.selected.classList.add("selection");
+      }
+    },
+
+    /**
+     * Remove selection if selected exists and different from current
+     */
+    _removeSelection() {
+      const { selected } = this.elements;
+
+      if (selected) {
+        selected.classList.remove("selection");
+      }
+    },
+
+    /**
+     * Compares arrays of objects. It assumes the structure is an array of
+     * objects, and objects in a and b have the same number of properties.
+     *
+     * @param  {Array<Object>} a
+     * @param  {Array<Object>} b
+     * @return {Boolean}  Returns true if a and b are different
+     */
+    _isArrayDiff(a, b) {
+      // Check reference first, exit early if reference is the same.
+      if (a == b) {
+        return false;
+      }
+
+      if (a.length != b.length) {
+        return true;
+      }
+
+      for (let i = 0; i < a.length; i++) {
+        for (let prop in a[i]) {
+          if (a[i][prop] != b[i][prop]) {
+            return true;
+          }
+        }
+      }
+      return false;
+    },
+
+    /**
+     * While the spinner is focused and keyboard command is used, selects an
+     * appropriate index and centers it, while preventing default behavior and
+     * stopping event propagation.
+     *
+     * @param {Object} event: Keyboard event
+     * @param {Number} index: The index of the expected next item
+     */
+    _setValueForSpinner(event, index) {
+      this._smoothScrollToIndex(index);
+      event.stopPropagation();
+      event.preventDefault();
+    },
+  };
+}