Treeview

An accessible treeview navigation in the DOM.

Note

This is a subclass of BaseMenu.

Constructor

Constructs a new Treeview.

new Treeview({
  menuElement,
  menuItemSelector,
  menuLinkSelector,
  submenuItemSelector,
  submenuToggleSelector,
  submenuSelector,
  controllerElement,
  containerElement,
  openClass,
  closeClass,
  transitionClass,
  transitionDuration,
  openDuration,
  closeDuration,
  isTopLevel,
  parentMenu,
  hoverType,
  hoverDelay,
  enterDelay,
  leaveDelay,
  prefix,
  initialize,
});

The constructor will call BaseMenu's constructor with the provided options. It will also initialize the menu if the initialize flag is set to true.

Parameters

Name	Type	Description	Default
options	object	The options for generating the menu.	undefined
options.menuElement	HTMLElement	The menu element in the DOM.	undefined
options.menuItemSelector	string	The query selector string for menu items.	"li"
options.menuLinkSelector	string	The query selector string for menu links.	"a"
options.submenuItemSelector	string	The query selector string for menu items containing submenus.	li:has(ul)
options.submenuToggleSelector	string	The query selector string for submenu toggle buttons/links.	"a"
options.submenuSelector	string	The query selector string for submenus.	"ul"
options.controllerElement	HTMLElement, null	The element controlling the menu in the DOM.	null
options.containerElement	HTMLElement, null	The element containing the menu in the DOM.	null
options.openClass	string, string[], null	The class to apply when a menu is "open".	null
options.closeClass	string, string[], null	The class to apply when a menu is "closed".	null
options.transitionClass	string, string[], null	The class to apply when a menu is transitioning between "open" and "closed" states.	null
options.transitionDuration	number	The duration of the transition between "open" and "closed" states (in milliseconds).	250
options.openDuration	number	The duration of the transition from "closed" to "open" states (in milliseconds).	250
options.closeDuration	number	The duration of the transition from "open" to "closed" states (in milliseconds).	250
options.isTopLevel	boolean	A flag to mark the root menu.	true
options.parentMenu	Treeview, null	The parent menu to this menu.	null
options.hoverType	string	The type of hoverability a menu has.	"off"
options.hoverDelay	number	The delay for opening and closing menus if the menu is hoverable (in milliseconds).	250
options.enterDelay	number	The delay for opening a menu if the menu is focusable (in milliseconds).	-1
options.leaveDelay	number	The delay for closing a menu if the menu is focusable (in milliseconds).	-1
options.prefix	string, null	The prefix for the CSS custom properties.	"am-"
options.initialize	boolean	A flag to initialize the menu immediately upon creation.	true

Initialize

Initializes the menu.

Treeview.initialize();

Initialize will call BaseMenu's initialize method as well as set up focus (inherited), click (inherited), hover (inherited), keydown, and keyup events for the menu.

If the menu is a root menu it's role will be set to "tree" and the first menu item's tabIndex will be set to 0 in the DOM.

If the menu is not a root menu it's role will be set to "group".

If the BaseMenu's initialize method throws an error, this will catch it and log it to the console.

Properties

Properties are inherited from the BaseMenu class. The following properties are unique to or overwritten in the Treeview class.

_MenuType protected

The class to use when generating submenus.

Treeview._MenuType; // Default: `Treeview`.

Type

Class

_MenuItemType protected

The class to use when generating menu items.

Treeview._MenuItemType; // Default: `TreeviewItem`.

Type

Class

_MenuToggleType protected

The class to use when generating menu toggles.

Treeview._MenuToggleType; // Default: `TreeviewToggle`.

Type

Class

Getters and Setters

Getters and setters are inherited from the BaseMenu class. The following getters and setters are unique to or overwritten in the Treeview class.

Methods

Methods are inherited from the BaseMenu class. The following methods are unique to or overwritten in the Treeview class.

_handleHover protected

Handles hover events throughout the menu for proper use.

BaseMenu._handleHover();

Adds pointerenter listeners to all menu items and pointerleave listeners to all submenu items which function differently depending on the menu's hover type.

Before executing anything, the event is checked to make sure the event wasn't triggered by a pen or touch.

This method will add the following behaviour:

Hover Type "on"

• When a pointerenter event triggers on any menu item the menu's current child value will change to that menu item.
• When a pointerenter event triggers on a submenu item the preview method for the submenu item's toggle will be called.
• When a pointerleave event triggers on the menu itself the closeChildren method will be called after a delay set by the menu's hover delay.

Hover Type "dynamic"

• When a pointerenter event triggers on any menu item the menu's current child value will change to that menu item.
• When a pointerenter event triggers on any menu item, and the menu's focus state is not "none", the menu item will be focused.
• When a pointerenter event triggers on a submenu item, and a submenu is already open, the preview method for the submenu item's toggle will be called.
• When a pointerenter event triggers on a non-submenu item, and a submenu is already open, the closeChildren method for the menu will be called.
• When a pointerenter event triggers on a submenu item, and no submenu is open, no submenu-specific methods will be called.

Hover Type "off"

All pointerenter and pointerleave events are ignored.

_handleKeydown protected

Handles keydown events throughout the menu for proper menu use.

Treeview._handleKeydown();

This method exists to assist the _handleKeyup method.

This method will do the following:

• Adds all keydown listeners from BaseMenu's _handleKeydown method.
• Adds a keydown listener to the menu/all submenus.
  • Blocks propagation on the following keys: "ArrowUp", "ArrowRight", "ArrowDown", "ArrowLeft", "Home", "End", "Space", "Enter", "Escape", "*" (asterisk), and "A" through "Z".
  • Moves focus out if the "Tab" key is pressed.

_handleKeyup protected

Handles keyup events throughout the menu for proper menu use.

Treeview._handleKeyup();

Adds all keyup listeners from BaseMenu's _handleKeyup method.

Adds the following keybindings (explanations are taken from the Navigation Treeview Example Using Computed Properties):

Key	Function
Enter or Space	Performs the default action (e.g. onclick event) for the focused node.
Down arrow	Moves focus to the next node that is focusable without opening or closing a node. If focus is on the last node, does nothing.
Up arrow	Moves focus to the previous node that is focusable without opening or closing a node. If focus is on the first node, does nothing.
Right arrow	When focus is on a closed node, opens the node; focus does not move. When focus is on a open node, moves focus to the first child node. When focus is on an end node, does nothing.
Left arrow	When focus is on an open node, closes the node. When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. When focus is on a root node that is also either an end node or a closed node, does nothing.
Home	Moves focus to first node without opening or closing a node.
End	Moves focus to the last node that can be focused without expanding any nodes that are closed.
a-z, A-Z	Focus moves to the next node with a name that starts with the typed character. Search wraps to first node if a matching name is not found among the nodes that follow the focused node. Search ignores nodes that are descendants of closed nodes.
* (asterisk)	Expands all closed sibling nodes that are at the same level as the focused node. Focus does not move.
Escape	If the root menu is collapsible, collapses the menu and focuses the menu's controlling element.

focusLastNode public

Focus the menu's last node of the entire expanded menu.

Treeview.focusLastNode();

This includes all open child menu items.

openChildren public

Open all submenu children.

Treeview.openChildren();

focusNextNodeWithCharacter public

Focus the menu's next node starting with a specific letter.

Treeview.focusNextNodeWithCharacter(char);

This includes all open child menu items.

Wraps to the first node if no match is found after the current node.

Parameters

Name	Type	Description	Default
char	string	The character to look for.	undefined

focusParentsNextChild public

Focus the parent menu's next child.

Treeview.focusParentsNextChild();

This will cascade up through to the root menu.

focusChildsLastNode public

Focus the last child of the current child's submenu.

Treeview.focusChildsLastNode();

This will cascade down through to the last open menu.