Source code
Revision control
Copy as Markdown
Other Tools
/* 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
"use strict";
// Make this available to both AMD and CJS environments
define(function (require, exports, module) {
const {
cloneElement,
Component,
createFactory,
createRef,
} = require("resource://devtools/client/shared/vendor/react.js");
const {
findDOMNode,
} = require("resource://devtools/client/shared/vendor/react-dom.js");
const PropTypes = require("resource://devtools/client/shared/vendor/react-prop-types.js");
const dom = require("resource://devtools/client/shared/vendor/react-dom-factories.js");
// Reps
const {
ObjectProvider,
} = require("resource://devtools/client/shared/components/tree/ObjectProvider.js");
const TreeRow = createFactory(
require("resource://devtools/client/shared/components/tree/TreeRow.js")
);
const TreeHeader = createFactory(
require("resource://devtools/client/shared/components/tree/TreeHeader.js")
);
const {
scrollIntoView,
} = require("resource://devtools/client/shared/scroll.js");
const SUPPORTED_KEYS = [
"ArrowUp",
"ArrowDown",
"ArrowLeft",
"ArrowRight",
"End",
"Home",
"Enter",
" ",
"Escape",
];
const defaultProps = {
object: null,
renderRow: null,
provider: ObjectProvider,
expandedNodes: new Set(),
selected: null,
defaultSelectFirstNode: true,
active: null,
expandableStrings: true,
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,
// 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,
// Array of columns
columns: PropTypes.arrayOf(
PropTypes.shape({
id: PropTypes.string.isRequired,
title: PropTypes.string,
width: PropTypes.string,
})
),
};
}
static get defaultProps() {
return defaultProps;
}
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);
}
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 } = this.props;
let children = provider.getChildren(parent) || [];
// 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)) {
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) {
return typeof value == "string" && value.length > 50;
}
// Exports from this module
module.exports = TreeView;
});