| // Copyright 2018 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| 'use strict'; |
| |
| /** |
| * @fileoverview |
| * Base class and helpers for tree navigation UI with collapsible branches and |
| * keyboard navigation. |
| */ |
| |
| /** |
| * Base class for UI to render and navigate a tree structure. In DOM this is |
| * rendered as a nested <ul> with <li> for each vertex. Each vertex can be: |
| * * A "group" containing <a class="node"> for structure. A group can be |
| * expanded or unexpanded, and is controlled by the base class. |
| * * A "leaf" containing <span class="node"> for data ldaves. A leaf is |
| , controlled by derived classes. |
| * Element rendering is done by derived classes, using custom templates. |
| * |
| * @template NODE_DATA_TYPE The data type of a tree node (groups and leaves) |
| */ |
| class TreeUi { |
| /** @param {!HTMLUListElement} rootElt */ |
| constructor(rootElt) { |
| /** @protected @const {!HTMLUListElement} rootElt */ |
| this.rootElt = rootElt; |
| |
| /** |
| * @protected {HTMLCollectionOf<!TreeNodeElement>} Collection of all tree |
| * node elements. Updates itself automatically. |
| */ |
| this.liveNodeList = |
| /** @type {HTMLCollectionOf<!TreeNodeElement>} */ ( |
| rootElt.getElementsByClassName('node')); |
| |
| /** |
| * @protected @const {!WeakMap<HTMLElement, Readonly<NODE_DATA_TYPE>>} |
| * Maps from UI nodes to data object to enable queries by event listeners |
| * and other methods. |
| */ |
| this.uiNodeToData = new WeakMap(); |
| |
| /** @private @const {function(!MouseEvent): *} */ |
| this.boundToggleGroupElement = this.toggleGroupElement.bind(this); |
| } |
| |
| /** |
| * Decides whether |elt| is the node of a leaf or an unexpanded group. |
| * @param {!HTMLElement} elt |
| * @return {boolean} |
| * @protected |
| */ |
| isTerminalElement(elt) { |
| return elt.classList.contains('node') && |
| elt.getAttribute('aria-expanded') === null; |
| } |
| |
| /** |
| * Sets focus to a new tree element while updating the element that last had |
| * focus. The tabindex property is used to avoid needing to tab through every |
| * single tree item in the page to reach other areas. |
| * @param {?TreeNodeElement} nodeElt A tree node element. |
| * @protected |
| */ |
| setFocusElement(nodeElt) { |
| const lastFocused = /** @type {HTMLElement} */ (document.activeElement); |
| // If the last focused element was a tree node element, change its tabindex. |
| if (this.uiNodeToData.has(lastFocused)) |
| lastFocused.tabIndex = -1; |
| if (nodeElt) { |
| nodeElt.tabIndex = 0; |
| nodeElt.focus(); |
| } |
| } |
| |
| /** |
| * Same as setFocusElement(), but takes index into |liveNodeList| instead. |
| * @param {number} index |
| * @protected |
| */ |
| setFocusElementByIndex(index) { |
| this.setFocusElement(this.liveNodeList[index]); |
| } |
| |
| /** |
| * Creates an element for |nodeData| to represent a group or a leaf, which |
| * depends on whether there are >= 1 children. May bind events. |
| * @param {!NODE_DATA_TYPE} nodeData |
| * @return {!{fragment: !DocumentFragment, isLeaf: boolean}} |
| * @abstract @protected |
| */ |
| makeGroupOrLeafFragment(nodeData) { |
| return null; |
| } |
| |
| /** |
| * Creates an Element for |nodeData|, and binds click on group nodes to |
| * toggleGroupElement(). |
| * @param {!NODE_DATA_TYPE} nodeData |
| * @return {!DocumentFragment} |
| * @public |
| */ |
| makeNodeElement(nodeData) { |
| const {fragment, isLeaf} = this.makeGroupOrLeafFragment(nodeData); |
| const nodeElt = /** @type {TreeNodeElement} */ ( |
| assertNotNull(fragment.querySelector('.node'))); |
| |
| // Associate clickable node & tree data. |
| this.uiNodeToData.set(nodeElt, Object.freeze(nodeData)); |
| |
| // Add click-to-toggle to group nodes. |
| if (!isLeaf) |
| nodeElt.addEventListener('click', this.boundToggleGroupElement); |
| |
| return fragment; |
| } |
| |
| /** |
| * Gets data for children of a group. Note that |link| is passed instead |
| * @param {!HTMLAnchorElement} link |
| * @return {!Promise<!Array<!NODE_DATA_TYPE>>} |
| * @abstract @protected |
| */ |
| async getGroupChildrenData(link) { |
| return null; |
| } |
| |
| /** |
| * @param {!HTMLAnchorElement} link |
| * @return {!HTMLLIElement} |
| * @protected |
| */ |
| getTreeItemFromLink(link) { |
| // Canonical structure: |
| // <li> <!-- |treeitem| --> |
| // <a class="node">...</a> <!-- |link| --> |
| // <ul>...</ul> <!-- |group| --> |
| // </li> |
| return /** @type {!HTMLLIElement} */ (link.parentElement); |
| } |
| |
| /** |
| * @param {!HTMLAnchorElement} link |
| * @return {!HTMLUListElement} |
| * @protected |
| */ |
| getGroupFromLink(link) { |
| return /** @type {!HTMLUListElement} */ (link.nextElementSibling); |
| } |
| |
| /** |
| * @param {!HTMLElement} link |
| * @param {!Array<DocumentFragment>} childrenElements |
| * @protected |
| */ |
| autoExpandAttentionWorthyChild(link, childrenElements) { |
| if (childrenElements.length === 1) { |
| // Open inner element if it only has a single child; this ensures nodes |
| // like "java"->"com"->"google" are opened all at once. |
| const node = /** @type {!TreeNodeElement} */ ( |
| childrenElements[0].querySelector('.node')); |
| node.click(); |
| } |
| } |
| |
| /** |
| * Populates |link| with |
| * @param {!HTMLAnchorElement} link |
| * @protected |
| */ |
| async expandGroupElement(link) { |
| const childrenData = await this.getGroupChildrenData(link); |
| const newElements = childrenData.map((data) => this.makeNodeElement(data)); |
| this.autoExpandAttentionWorthyChild(link, newElements); |
| const newElementsFragment = dom.createFragment(newElements); |
| requestAnimationFrame(() => { |
| this.getGroupFromLink(link).appendChild(newElementsFragment); |
| }); |
| } |
| |
| /** |
| * Click event handler to expand or close a group node. |
| * @param {Event} event |
| * @protected |
| */ |
| async toggleGroupElement(event) { |
| event.preventDefault(); |
| const link = /** @type {!HTMLAnchorElement} */ (event.currentTarget); |
| const treeitem = this.getTreeItemFromLink(link); |
| const group = this.getGroupFromLink(link); |
| |
| const isExpanded = treeitem.getAttribute('aria-expanded') === 'true'; |
| if (isExpanded) { |
| // Take keyboard focus from descendent node. |
| const lastFocused = /** @type {HTMLElement} */ (document.activeElement); |
| if (lastFocused && group.contains(lastFocused)) |
| this.setFocusElement(link); |
| // Update DOM. |
| treeitem.setAttribute('aria-expanded', 'false'); |
| dom.replace(group, null); |
| } else { |
| treeitem.setAttribute('aria-expanded', 'true'); |
| await this.expandGroupElement(link); |
| } |
| } |
| |
| /** |
| * Helper to handle tree navigation on keydown event. |
| * @param {!KeyboardEvent} event Event passed from keydown event listener. |
| * @param {!TreeNodeElement} link Tree node element, either a group or leaf. |
| * Trees use <a> tags, leaves use <span> tags. For example, see |
| * #tmpl-symbol-tree-group and #tmpl-symbol-tree-leaf. |
| * @param {number} focusIndex |
| * @return {boolean} Whether the event is handled. |
| * @protected |
| */ |
| handleKeyNavigationCommon(event, link, focusIndex) { |
| /** Focuses the tree element immediately following this one. */ |
| const focusNext = () => { |
| if (focusIndex > -1 && focusIndex < this.liveNodeList.length - 1) { |
| event.preventDefault(); |
| this.setFocusElementByIndex(focusIndex + 1); |
| } |
| }; |
| |
| /** Opens or closes the tree element. */ |
| const toggle = () => { |
| event.preventDefault(); |
| /** @type {HTMLAnchorElement} */ (link).click(); |
| }; |
| |
| switch (event.key) { |
| // Space should act like clicking or pressing enter & toggle the tree. |
| case ' ': |
| toggle(); |
| return true; |
| // Move to previous focusable node. |
| case 'ArrowUp': |
| if (focusIndex > 0) { |
| event.preventDefault(); |
| this.setFocusElementByIndex(focusIndex - 1); |
| } |
| return true; |
| // Move to next focusable node. |
| case 'ArrowDown': |
| focusNext(); |
| return true; |
| // If closed tree, open tree. Otherwise, move to first child. |
| case 'ArrowRight': { |
| const expanded = link.parentElement.getAttribute('aria-expanded'); |
| // Handle groups only (leaves do not have aria-expanded property). |
| if (expanded !== null) { |
| if (expanded === 'true') { |
| focusNext(); |
| } else { |
| toggle(); |
| } |
| } |
| return true; |
| } |
| // If opened tree, close tree. Otherwise, move to parent. |
| case 'ArrowLeft': { |
| const isExpanded = |
| link.parentElement.getAttribute('aria-expanded') === 'true'; |
| if (isExpanded) { |
| toggle(); |
| } else { |
| const groupList = link.parentElement.parentElement; |
| if (groupList.getAttribute('role') === 'group') { |
| event.preventDefault(); |
| /** @type {HTMLAnchorElement} */ |
| const parentLink = /** @type {HTMLAnchorElement} */ ( |
| groupList.previousElementSibling); |
| this.setFocusElement(parentLink); |
| } |
| } |
| return true; |
| } |
| // Focus first node. |
| case 'Home': |
| event.preventDefault(); |
| this.setFocusElementByIndex(0); |
| return true; |
| // Focus last node on screen. |
| case 'End': |
| event.preventDefault(); |
| this.setFocusElementByIndex(this.liveNodeList.length - 1); |
| return true; |
| // Expand all sibling nodes. |
| case '*': |
| const groupList = link.parentElement.parentElement; |
| if (groupList.getAttribute('role') === 'group') { |
| event.preventDefault(); |
| for (const li of groupList.children) { |
| if (li.getAttribute('aria-expanded') !== 'true') { |
| const otherLink = |
| /** @type {!TreeNodeElement} */ (li.querySelector('.node')); |
| otherLink.click(); |
| } |
| } |
| } |
| return true; |
| // Remove focus from the tree view. |
| case 'Escape': |
| link.blur(); |
| return true; |
| } |
| |
| return false; |
| } |
| |
| /** |
| * Handler for gaining focus relative to other TreeUi instances. |
| * @protected |
| */ |
| onTreeFocus() {} |
| |
| /** |
| * Handler for losing focus relative to other TreeUi instances, i.e., this |
| * does NOT fire when non-TreeUi UI elements gain focus. |
| * @protected |
| */ |
| onTreeBlur() {} |
| |
| /** @public */ |
| focus() { |
| if (TreeUi.activeTreeUi !== this) { |
| if (TreeUi.activeTreeUi) |
| TreeUi.activeTreeUi.onTreeBlur(); |
| TreeUi.activeTreeUi = this; |
| TreeUi.activeTreeUi.onTreeFocus(); |
| } |
| } |
| |
| /** @public */ |
| init() { |
| // Each instance contributes to managing focus / blur dynamics. |
| this.rootElt.addEventListener('click', () => this.focus()); |
| } |
| } |
| |
| /** @type {?TreeUi} */ |
| TreeUi.activeTreeUi = null; |
