tor-browser

TreeView.mjs (23529B)

---

/* 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/. */

/* eslint no-shadow: ["error", { "allow": ["open", "parent"] }] */

import React from "resource://devtools/client/shared/vendor/react.mjs";
import ReactDOM from "resource://devtools/client/shared/vendor/react-dom.mjs";
import PropTypes from "resource://devtools/client/shared/vendor/react-prop-types.mjs";
import * as dom from "resource://devtools/client/shared/vendor/react-dom-factories.mjs";

import { ObjectProvider } from "resource://devtools/client/shared/components/tree/ObjectProvider.mjs";
import TreeRowClass from "resource://devtools/client/shared/components/tree/TreeRow.mjs";
import TreeHeaderClass from "resource://devtools/client/shared/components/tree/TreeHeader.mjs";

import { scrollIntoView } from "resource://devtools/client/shared/scroll.mjs";

const { cloneElement, Component, createFactory, createRef } = React;
const { findDOMNode } = ReactDOM;

const TreeRow = createFactory(TreeRowClass);
const TreeHeader = createFactory(TreeHeaderClass);

const SUPPORTED_KEYS = [
 "ArrowUp",
 "ArrowDown",
 "ArrowLeft",
 "ArrowRight",
 "End",
 "Home",
 "Enter",
 " ",
 "Escape",
];

// Use a function in order to avoid shared Set/Array between each instance!
function getDefaultProps() {
 return {
   object: null,
   renderRow: null,
   provider: ObjectProvider,
   expandedNodes: new Set(),
   selected: null,
   defaultSelectFirstNode: true,
   active: null,
   expandableStrings: true,
   bucketLargeArrays: false,
   maxStringLength: 50,
   columns: [],
 };
}

/**
* This component represents a tree view with expandable/collapsible nodes.
* The tree is rendered using <table> element where every node is represented
* by <tr> element. The tree is one big table where nodes (rows) are properly
* indented from the left to mimic hierarchical structure of the data.
*
* The tree can have arbitrary number of columns and so, might be use
* as an expandable tree-table UI widget as well. By default, there is
* one column for node label and one for node value.
*
* The tree is maintaining its (presentation) state, which consists
* from list of expanded nodes and list of columns.
*
* Complete data provider interface:
* var TreeProvider = {
*   getChildren: function(object);
*   hasChildren: function(object);
*   getLabel: function(object, colId);
*   getLevel: function(object); // optional
*   getValue: function(object, colId);
*   getKey: function(object);
*   getType: function(object);
* }
*
* Complete tree decorator interface:
* var TreeDecorator = {
*   getRowClass: function(object);
*   getCellClass: function(object, colId);
*   getHeaderClass: function(colId);
*   renderValue: function(object, colId);
*   renderRow: function(object);
*   renderCell: function(object, colId);
*   renderLabelCell: function(object);
* }
*/
class TreeView extends Component {
 // The only required property (not set by default) is the input data
 // object that is used to populate the tree.
 static get propTypes() {
   return {
     // The input data object.
     object: PropTypes.any,
     className: PropTypes.string,
     label: PropTypes.string,
     // Data provider (see also the interface above)
     provider: PropTypes.shape({
       getChildren: PropTypes.func,
       hasChildren: PropTypes.func,
       getLabel: PropTypes.func,
       getValue: PropTypes.func,
       getKey: PropTypes.func,
       getLevel: PropTypes.func,
       getType: PropTypes.func,
     }).isRequired,
     // Tree decorator (see also the interface above)
     decorator: PropTypes.shape({
       getRowClass: PropTypes.func,
       getCellClass: PropTypes.func,
       getHeaderClass: PropTypes.func,
       renderValue: PropTypes.func,
       renderRow: PropTypes.func,
       renderCell: PropTypes.func,
       renderLabelCell: PropTypes.func,
     }),
     // Custom tree row (node) renderer
     renderRow: PropTypes.func,
     // Custom cell renderer
     renderCell: PropTypes.func,
     // Custom value renderer
     renderValue: PropTypes.func,
     // Custom tree label (including a toggle button) renderer
     renderLabelCell: PropTypes.func,
     // Set of expanded nodes
     expandedNodes: PropTypes.object,
     // Selected node
     selected: PropTypes.string,
     // Select first node by default
     defaultSelectFirstNode: PropTypes.bool,
     // The currently active (keyboard) item, if any such item exists.
     active: PropTypes.string,
     // Custom filtering callback
     onFilter: PropTypes.func,
     // Custom sorting callback
     onSort: PropTypes.func,
     // Enable bucketing for large arrays
     bucketLargeArrays: PropTypes.bool,
     // Custom row click callback
     onClickRow: PropTypes.func,
     // Row context menu event handler
     onContextMenuRow: PropTypes.func,
     // Tree context menu event handler
     onContextMenuTree: PropTypes.func,
     // A header is displayed if set to true
     header: PropTypes.bool,
     // Long string is expandable by a toggle button
     expandableStrings: PropTypes.bool,
     // Length at which a string is considered long
     maxStringLength: PropTypes.number,
     // Array of columns
     columns: PropTypes.arrayOf(
       PropTypes.shape({
         id: PropTypes.string.isRequired,
         title: PropTypes.string,
         width: PropTypes.string,
       })
     ),
   };
 }

 static get defaultProps() {
   return getDefaultProps();
 }

 static subPath(path, subKey) {
   return path + "/" + String(subKey).replace(/[\\/]/g, "\\$&");
 }

 /**
  * Creates a set with the paths of the nodes that should be expanded by default
  * according to the passed options.
  *
  * @param {object} The root node of the tree.
  * @param {object} [optional] An object with the following optional parameters:
  *   - maxLevel: nodes nested deeper than this level won't be expanded.
  *   - maxNodes: maximum number of nodes that can be expanded. The traversal is
        breadth-first, so expanding nodes nearer to the root will be preferred.
        Sibling nodes will either be all expanded or none expanded.
  * }
  */
 static getExpandedNodes(
   rootObj,
   { maxLevel = Infinity, maxNodes = Infinity } = {}
 ) {
   const expandedNodes = new Set();
   const queue = [
     {
       object: rootObj,
       level: 1,
       path: "",
     },
   ];
   while (queue.length) {
     const { object, level, path } = queue.shift();
     if (Object(object) !== object) {
       continue;
     }
     const keys = Object.keys(object);
     if (expandedNodes.size + keys.length > maxNodes) {
       // Avoid having children half expanded.
       break;
     }
     for (const key of keys) {
       const nodePath = TreeView.subPath(path, key);
       expandedNodes.add(nodePath);
       if (level < maxLevel) {
         queue.push({
           object: object[key],
           level: level + 1,
           path: nodePath,
         });
       }
     }
   }
   return expandedNodes;
 }

 constructor(props) {
   super(props);

   this.state = {
     expandedNodes: props.expandedNodes,
     columns: ensureDefaultColumn(props.columns),
     selected: props.selected,
     active: props.active,
     lastSelectedIndex: props.defaultSelectFirstNode ? 0 : null,
     mouseDown: false,
   };

   this.treeRef = createRef();

   this.toggle = this.toggle.bind(this);
   this.isExpanded = this.isExpanded.bind(this);
   this.onFocus = this.onFocus.bind(this);
   this.onKeyDown = this.onKeyDown.bind(this);
   this.onClickRow = this.onClickRow.bind(this);
   this.getSelectedRow = this.getSelectedRow.bind(this);
   this.selectRow = this.selectRow.bind(this);
   this.activateRow = this.activateRow.bind(this);
   this.isSelected = this.isSelected.bind(this);
   this.onFilter = this.onFilter.bind(this);
   this.onSort = this.onSort.bind(this);
   this.getMembers = this.getMembers.bind(this);
   this.renderRows = this.renderRows.bind(this);
 }

 // FIXME: https://bugzilla.mozilla.org/show_bug.cgi?id=1774507
 UNSAFE_componentWillReceiveProps(nextProps) {
   const { expandedNodes, selected } = nextProps;
   const state = {
     expandedNodes,
     lastSelectedIndex: this.getSelectedRowIndex(),
   };

   if (selected) {
     state.selected = selected;
   }

   this.setState(Object.assign({}, this.state, state));
 }

 shouldComponentUpdate(nextProps, nextState) {
   const {
     expandedNodes,
     columns,
     selected,
     active,
     lastSelectedIndex,
     mouseDown,
   } = this.state;

   return (
     expandedNodes !== nextState.expandedNodes ||
     columns !== nextState.columns ||
     selected !== nextState.selected ||
     active !== nextState.active ||
     lastSelectedIndex !== nextState.lastSelectedIndex ||
     mouseDown === nextState.mouseDown
   );
 }

 componentDidUpdate() {
   const selected = this.getSelectedRow();
   if (selected || this.state.active) {
     return;
   }

   const rows = this.visibleRows;
   if (rows.length === 0) {
     return;
   }

   // Only select a row if there is a previous lastSelected Index
   // This mostly happens when the treeview is loaded the first time
   if (this.state.lastSelectedIndex !== null) {
     this.selectRow(
       rows[Math.min(this.state.lastSelectedIndex, rows.length - 1)],
       { alignTo: "top" }
     );
   }
 }

 /**
  * Get rows that are currently visible. Some rows can be filtered and made
  * invisible, in which case, when navigating around the tree we need to
  * ignore the ones that are not reachable by the user.
  */
 get visibleRows() {
   return this.rows.filter(row => {
     const rowEl = findDOMNode(row);
     return rowEl?.offsetParent;
   });
 }

 // Node expand/collapse

 toggle(nodePath) {
   const nodes = this.state.expandedNodes;
   if (this.isExpanded(nodePath)) {
     nodes.delete(nodePath);
   } else {
     nodes.add(nodePath);
   }

   // Compute new state and update the tree.
   this.setState(
     Object.assign({}, this.state, {
       expandedNodes: nodes,
     })
   );
 }

 isExpanded(nodePath) {
   return this.state.expandedNodes.has(nodePath);
 }

 // Event Handlers

 onFocus(_event) {
   if (this.state.mouseDown) {
     return;
   }
   // Set focus to the first element, if none is selected or activated
   // This is needed because keyboard navigation won't work without an element being selected
   this.componentDidUpdate();
 }

 // eslint-disable-next-line complexity
 onKeyDown(event) {
   const keyEligibleForFirstLetterNavigation = event.key.length === 1;
   if (
     (!SUPPORTED_KEYS.includes(event.key) &&
       !keyEligibleForFirstLetterNavigation) ||
     event.shiftKey ||
     event.ctrlKey ||
     event.metaKey ||
     event.altKey
   ) {
     return;
   }

   const row = this.getSelectedRow();
   if (!row) {
     return;
   }

   const rows = this.visibleRows;
   const index = rows.indexOf(row);
   const { hasChildren, open } = row.props.member;

   switch (event.key) {
     case "ArrowRight":
       if (hasChildren) {
         if (open) {
           const firstChildRow = this.rows
             .slice(index + 1)
             .find(r => r.props.member.level > row.props.member.level);
           if (firstChildRow) {
             this.selectRow(firstChildRow, { alignTo: "bottom" });
           }
         } else {
           this.toggle(this.state.selected);
         }
       }
       break;
     case "ArrowLeft":
       if (hasChildren && open) {
         this.toggle(this.state.selected);
       } else {
         const parentRow = rows
           .slice(0, index)
           .reverse()
           .find(r => r.props.member.level < row.props.member.level);
         if (parentRow) {
           this.selectRow(parentRow, { alignTo: "top" });
         }
       }
       break;
     case "ArrowDown": {
       const nextRow = rows[index + 1];
       if (nextRow) {
         this.selectRow(nextRow, { alignTo: "bottom" });
       }
       break;
     }
     case "ArrowUp": {
       const previousRow = rows[index - 1];
       if (previousRow) {
         this.selectRow(previousRow, { alignTo: "top" });
       }
       break;
     }
     case "Home": {
       const firstRow = rows[0];

       if (firstRow) {
         this.selectRow(firstRow, { alignTo: "top" });
       }
       break;
     }
     case "End": {
       const lastRow = rows[rows.length - 1];
       if (lastRow) {
         this.selectRow(lastRow, { alignTo: "bottom" });
       }
       break;
     }
     case "Enter":
     case " ":
       // On space or enter make selected row active. This means keyboard
       // focus handling is passed on to the tree row itself.
       if (this.treeRef.current === document.activeElement) {
         event.stopPropagation();
         event.preventDefault();
         if (this.state.active !== this.state.selected) {
           this.activateRow(this.state.selected);
         }

         return;
       }
       break;
     case "Escape":
       event.stopPropagation();
       if (this.state.active != null) {
         this.activateRow(null);
       }
       break;
   }

   if (keyEligibleForFirstLetterNavigation) {
     const next = rows
       .slice(index + 1)
       .find(r => r.props.member.name.startsWith(event.key));
     if (next) {
       this.selectRow(next, { alignTo: "bottom" });
     }
   }

   // Focus should always remain on the tree container itself.
   this.treeRef.current.focus();
   event.preventDefault();
 }

 onClickRow(nodePath, event) {
   const onClickRow = this.props.onClickRow;
   const row = this.visibleRows.find(r => r.props.member.path === nodePath);

   // Call custom click handler and bail out if it returns true.
   if (
     onClickRow &&
     onClickRow.call(this, nodePath, event, row.props.member)
   ) {
     return;
   }

   event.stopPropagation();

   const cell = event.target.closest("td");
   if (cell && cell.classList.contains("treeLabelCell")) {
     this.toggle(nodePath);
   }

   this.selectRow(row, { preventAutoScroll: true });
 }

 onContextMenu(member, event) {
   const onContextMenuRow = this.props.onContextMenuRow;
   if (onContextMenuRow) {
     onContextMenuRow.call(this, member, event);
   }
 }

 getSelectedRow() {
   const rows = this.visibleRows;
   if (!this.state.selected || rows.length === 0) {
     return null;
   }
   return rows.find(row => this.isSelected(row.props.member.path));
 }

 getSelectedRowIndex() {
   const row = this.getSelectedRow();
   if (!row) {
     return this.props.defaultSelectFirstNode ? 0 : null;
   }

   return this.visibleRows.indexOf(row);
 }

 _scrollIntoView(row, options = {}) {
   const treeEl = this.treeRef.current;
   if (!treeEl || !row) {
     return;
   }

   const { props: { member: { path } = {} } = {} } = row;
   if (!path) {
     return;
   }

   const element = treeEl.ownerDocument.getElementById(path);
   if (!element) {
     return;
   }

   scrollIntoView(element, { ...options });
 }

 selectRow(row, options = {}) {
   const { props: { member: { path } = {} } = {} } = row;
   if (this.isSelected(path)) {
     return;
   }

   if (this.state.active != null) {
     const treeEl = this.treeRef.current;
     if (treeEl && treeEl !== treeEl.ownerDocument.activeElement) {
       treeEl.focus();
     }
   }

   if (!options.preventAutoScroll) {
     this._scrollIntoView(row, options);
   }

   this.setState({
     ...this.state,
     selected: path,
     active: null,
   });
 }

 activateRow(active) {
   this.setState({
     ...this.state,
     active,
   });
 }

 isSelected(nodePath) {
   return nodePath === this.state.selected;
 }

 isActive(nodePath) {
   return nodePath === this.state.active;
 }

 // Filtering & Sorting

 /**
  * Filter out nodes that don't correspond to the current filter.
  *
  * @return {boolean} true if the node should be visible otherwise false.
  */
 onFilter(object) {
   const onFilter = this.props.onFilter;
   return onFilter ? onFilter(object) : true;
 }

 onSort(parent, children) {
   const onSort = this.props.onSort;
   return onSort ? onSort(parent, children) : children;
 }

 // Members

 /**
  * Return children node objects (so called 'members') for given
  * parent object.
  */
 getMembers(parent, level, path) {
   // Strings don't have children. Note that 'long' strings are using
   // the expander icon (+/-) to display the entire original value,
   // but there are no child items.
   if (typeof parent == "string") {
     return [];
   }

   const { expandableStrings, provider, bucketLargeArrays, maxStringLength } =
     this.props;
   let children = provider.getChildren(parent, { bucketLargeArrays }) || [];

   // If the return value is non-array, the children
   // are being loaded asynchronously.
   if (!Array.isArray(children)) {
     return children;
   }

   children = this.onSort(parent, children) || children;

   return children.map(child => {
     const key = provider.getKey(child);
     const nodePath = TreeView.subPath(path, key);
     const type = provider.getType(child);
     let hasChildren = provider.hasChildren(child);

     // Value with no column specified is used for optimization.
     // The row is re-rendered only if this value changes.
     // Value for actual column is get when a cell is rendered.
     const value = provider.getValue(child);

     if (expandableStrings && isLongString(value, maxStringLength)) {
       hasChildren = true;
     }

     // Return value is a 'member' object containing meta-data about
     // tree node. It describes node label, value, type, etc.
     return {
       // An object associated with this node.
       object: child,
       // A label for the child node
       name: provider.getLabel(child),
       // Data type of the child node (used for CSS customization)
       type,
       // Class attribute computed from the type.
       rowClass: "treeRow-" + type,
       // Level of the child within the hierarchy (top == 0)
       level: provider.getLevel ? provider.getLevel(child, level) : level,
       // True if this node has children.
       hasChildren,
       // Value associated with this node (as provided by the data provider)
       value,
       // True if the node is expanded.
       open: this.isExpanded(nodePath),
       // Node path
       path: nodePath,
       // True if the node is hidden (used for filtering)
       hidden: !this.onFilter(child),
       // True if the node is selected with keyboard
       selected: this.isSelected(nodePath),
       // True if the node is activated with keyboard
       active: this.isActive(nodePath),
     };
   });
 }

 /**
  * Render tree rows/nodes.
  */
 renderRows(parent, level = 0, path = "") {
   let rows = [];
   const decorator = this.props.decorator;
   let renderRow = this.props.renderRow || TreeRow;

   // Get children for given parent node, iterate over them and render
   // a row for every one. Use row template (a component) from properties.
   // If the return value is non-array, the children are being loaded
   // asynchronously.
   const members = this.getMembers(parent, level, path);
   if (!Array.isArray(members)) {
     return members;
   }

   members.forEach(member => {
     if (decorator?.renderRow) {
       renderRow = decorator.renderRow(member.object) || renderRow;
     }

     const props = Object.assign({}, this.props, {
       key: `${member.path}-${member.active ? "active" : "inactive"}`,
       member,
       columns: this.state.columns,
       id: member.path,
       ref: row => row && this.rows.push(row),
       onClick: this.onClickRow.bind(this, member.path),
       onContextMenu: this.onContextMenu.bind(this, member),
     });

     // Render single row.
     rows.push(renderRow(props));

     // If a child node is expanded render its rows too.
     if (member.hasChildren && member.open) {
       const childRows = this.renderRows(
         member.object,
         level + 1,
         member.path
       );

       // If children needs to be asynchronously fetched first,
       // set 'loading' property to the parent row. Otherwise
       // just append children rows to the array of all rows.
       if (!Array.isArray(childRows)) {
         const lastIndex = rows.length - 1;
         props.member.loading = true;
         rows[lastIndex] = cloneElement(rows[lastIndex], props);
       } else {
         rows = rows.concat(childRows);
       }
     }
   });

   return rows;
 }

 render() {
   const root = this.props.object;
   const classNames = ["treeTable"];
   this.rows = [];

   const { className, onContextMenuTree } = this.props;
   // Use custom class name from props.
   if (className) {
     classNames.push(...className.split(" "));
   }

   // Alright, let's render all tree rows. The tree is one big <table>.
   let rows = this.renderRows(root, 0, "");

   // This happens when the view needs to do initial asynchronous
   // fetch for the root object. The tree might provide a hook API
   // for rendering animated spinner (just like for tree nodes).
   if (!Array.isArray(rows)) {
     rows = [];
   }

   const props = Object.assign({}, this.props, {
     columns: this.state.columns,
   });

   return dom.table(
     {
       className: classNames.join(" "),
       role: "tree",
       ref: this.treeRef,
       tabIndex: 0,
       onFocus: this.onFocus,
       onKeyDown: this.onKeyDown,
       onContextMenu: onContextMenuTree && onContextMenuTree.bind(this),
       onMouseDown: () => this.setState({ mouseDown: true }),
       onMouseUp: () => this.setState({ mouseDown: false }),
       onClick: () => {
         // Focus should always remain on the tree container itself.
         this.treeRef.current.focus();
       },
       onBlur: event => {
         if (this.state.active != null) {
           const { relatedTarget } = event;
           if (!this.treeRef.current.contains(relatedTarget)) {
             this.activateRow(null);
           }
         }
       },
       "aria-label": this.props.label || "",
       "aria-activedescendant": this.state.selected,
       cellPadding: 0,
       cellSpacing: 0,
     },
     TreeHeader(props),
     dom.tbody(
       {
         role: "presentation",
         tabIndex: -1,
       },
       rows
     )
   );
 }
}

// Helpers

/**
* There should always be at least one column (the one with toggle buttons)
* and this function ensures that it's true.
*/
function ensureDefaultColumn(columns) {
 if (!columns) {
   columns = [];
 }

 const defaultColumn = columns.filter(col => col.id == "default");
 if (defaultColumn.length) {
   return columns;
 }

 // The default column is usually the first one.
 return [{ id: "default" }, ...columns];
}

function isLongString(value, maxStringLength) {
 return typeof value == "string" && value.length > maxStringLength;
}

// Exports from this module
export default TreeView;