Treeview

Treeview

An accessible treeview navigation in the DOM.

See Navigation Treeview Example Using Computed Properties

Constructor

new Treeview(options)

Description:

  • Constructs the menu.

Source:
Example
// Import the class.
import { Treeview } from "accessible-menu";

// Select the desired menu element.
const menuElement = document.querySelector("nav ul");

// Create the menu.
const menu = new Treeview({
  menuElement,
});
Parameters:
Name Type Description
options object

The options for generating the menu.

Properties
Name Type Attributes Default Description
menuElement HTMLElement

The menu element in the DOM.
menuItemSelector string <optional>
 li

The CSS selector string for menu items.
menuLinkSelector string <optional>
 a

The CSS selector string for menu links.
submenuItemSelector string <optional>

The CSS selector string for menu items containing submenus.
submenuToggleSelector string <optional>
 a

The CSS selector string for submenu toggle buttons/links.
submenuSelector string <optional>
 ul

The CSS selector string for submenus.
controllerElement HTMLElement | null <optional>
 null

The element controlling the menu in the DOM.
containerElement HTMLElement | null <optional>
 null

The element containing the menu in the DOM.
openClass string | Array.<string> | null <optional>
 show

The class to apply when a menu is "open".
closeClass string | Array.<string> | null <optional>
 hide

The class to apply when a menu is "closed".
isTopLevel boolean <optional>
 true

A flag to mark the root menu.
parentMenu Treeview | null <optional>
 null

The parent menu to this menu.
hoverType string <optional>
 off

The type of hoverability a menu has.
hoverDelay number <optional>
 250

The delay for closing menus if the menu is hoverable (in miliseconds).
initialize boolean <optional>
 true

A flag to initialize the menu immediately upon creation.

Extends

Members

(protected) _MenuType :Class.<Treeview>

Description:

  • The class to use when generating submenus.

Source:
Overrides:

The class to use when generating submenus.

Type:

(protected) _MenuItemType :Class.<TreeviewItem>

Description:

  • The class to use when generating menu items.

Source:
Overrides:

The class to use when generating menu items.

Type:

(protected) _MenuToggleType :Class.<TreeviewToggle>

Description:

  • The class to use when generating submenu toggles.

Source:
Overrides:

The class to use when generating submenu toggles.

Type:

(protected) _dom :Object.<HTMLElement, Array.<HTMLElement>>

Description:

  • The DOM elements within the menu.

Source:
Overrides:
Properties:
Name Type Description
menu HTMLElement

The menu element.
menuItems Array.<HTMLElement>

An array of menu items.
submenuItems Array.<HTMLElement>

An array of menu items that also contain submenu elements.
submenuToggles Array.<HTMLElement>

An array of menu links that function as submenu toggles.
submenus Array.<HTMLElement>

An array of submenu elements.
controller HTMLElement

The toggle for this menu.
container HTMLElement

The container for this menu.

The DOM elements within the menu.

Type:
  • Object.<HTMLElement, Array.<HTMLElement>>

(protected) _selectors :Object.<string>

Description:

  • The CSS selectors used by the menu to populate the dom.

Source:
Overrides:
Properties:
Name Type Description
menuItems string

The CSS selector for menu items.
menuLinks string

The CSS selector for menu links.
submenuItems string

The CSS selector for menu items containing submenus.
submenuToggles string

The CSS selector for menu links that function as submenu toggles.
submenus string

The CSS selector for for submenus.

The CSS selectors used by the menu to populate the dom.

Type:
  • Object.<string>

(protected) _elements :Object.<BaseMenu, BaseMenuToggle, Array.<BaseMenuItem>, Array.<BaseMenuToggle>>

Description:

  • The declared accessible-menu elements within the menu.

Source:
Overrides:
Properties:
Name Type Attributes Description
menuItems Array.<BaseMenuItem>

An array of menu items.
submenuToggles Array.<BaseMenuToggle>

An array of menu toggles.
controller BaseMenuToggle <nullable>

A menu toggle that controls this menu.
parentMenu BaseMenu <nullable>

The parent menu.
rootMenu BaseMenu <nullable>

The root menu of the menu tree.

The declared accessible-menu elements within the menu.

Type:

(protected) _openClass :string|Array.<string>

Description:

  • The class(es) to apply when the menu is open.

Source:
Overrides:

The class(es) to apply when the menu is open.

Type:
  • string | Array.<string>

(protected) _closeClass :string|Array.<string>

Description:

  • The class(es) to apply when the menu is closed.

Source:
Overrides:

The class(es) to apply when the menu is closed.

Type:
  • string | Array.<string>

(protected) _root :boolean

Description:

  • A flag marking the root menu.

Source:
Overrides:

A flag marking the root menu.

Type:
  • boolean

(protected) _currentChild :number

Description:

  • The index of the currently selected menu item in the menu.

Source:
Overrides:

The index of the currently selected menu item in the menu.

Type:
  • number

(protected) _focusState :string

Description:

  • The current state of the menu's focus.

Source:
Overrides:

The current state of the menu's focus.

Type:
  • string

(protected) _currentEvent :string

Description:

  • This last event triggered on the menu.

Source:
Overrides:

This last event triggered on the menu.

Type:
  • string

(protected) _hoverType :string

Description:

  • The type of hoverability for the menu.

Source:
Overrides:

The type of hoverability for the menu.

Type:
  • string

(protected) _hoverDelay :number

Description:

  • The delay time (in miliseconds) used for mouseout events to take place.

Source:
Overrides:

The delay time (in miliseconds) used for mouseout events to take place.

Type:
  • number

(readonly) dom :Object.<HTMLElement, Array.<HTMLElement>>

Description:

  • The DOM elements within the menu.

Source:
Overrides:
See:
  • _dom

The DOM elements within the menu.

Type:
  • Object.<HTMLElement, Array.<HTMLElement>>

(readonly) selectors :Object.<string>

Description:

  • The CSS selectors used by the menu to populate the dom.

Source:
Overrides:
See:
  • _selectors

The CSS selectors used by the menu to populate the dom.

Type:
  • Object.<string>

(readonly) elements :Object.<BaseMenu, BaseMenuToggle, Array.<BaseMenuItem>, Array.<BaseMenuToggle>>

Description:

  • The declared accessible-menu elements within the menu.

Source:
Overrides:
See:
  • _elements

The declared accessible-menu elements within the menu.

Type:

(readonly) isTopLevel :boolean

Description:

  • The flag marking the root menu.

Source:
Overrides:
See:
  • _root

The flag marking the root menu.

Type:
  • boolean

openClass :string|Array.<string>

Description:

  • The class(es) to apply when the menu is open.

    This functions differently for root vs. submenus. Submenus will always inherit their root menu's open class(es).

Source:
Overrides:
See:
  • _openClass

The class(es) to apply when the menu is open.

This functions differently for root vs. submenus. Submenus will always inherit their root menu's open class(es).

Type:
  • string | Array.<string>

closeClass :string|Array.<string>

Description:

  • The class(es) to apply when the menu is closed.

    This functions differently for root vs. submenus. Submenus will always inherit their root menu's close class(es).

Source:
Overrides:
See:
  • _closeClass

The class(es) to apply when the menu is closed.

This functions differently for root vs. submenus. Submenus will always inherit their root menu's close class(es).

Type:
  • string | Array.<string>

currentChild :number

Description:

  • The index of the currently selected menu item in the menu.

    • Attempting to set a value less than -1 will set the current child to -1.
    • Attempting to set a value greater than or equal to the number of menu items will set the current child to the index of the last menu item in the menu.

    If the current menu has a parent menu and the menu's current event is "mouse", The parent menu will have it's current child updated as well to help with transitioning between mouse and keyboard naviation.

Source:
Overrides:
See:
  • _currentChild

The index of the currently selected menu item in the menu.

  • Attempting to set a value less than -1 will set the current child to -1.
  • Attempting to set a value greater than or equal to the number of menu items will set the current child to the index of the last menu item in the menu.

If the current menu has a parent menu and the menu's current event is "mouse", The parent menu will have it's current child updated as well to help with transitioning between mouse and keyboard naviation.

Type:
  • number

focusState :string

Description:

  • The current state of the menu's focus.

    • If the menu has submenus, setting the focus state to "none" or "self" will update all child menus to have the focus state of "none".
    • If the menu has a parent menu, setting the focus state to "self" or "child" will update all parent menus to have the focus state of "child".
Source:
Overrides:
See:
  • _focusState

The current state of the menu's focus.

  • If the menu has submenus, setting the focus state to "none" or "self" will update all child menus to have the focus state of "none".
  • If the menu has a parent menu, setting the focus state to "self" or "child" will update all parent menus to have the focus state of "child".
Type:
  • string

currentEvent :string

Description:

  • The last event triggered on the menu.

Source:
Overrides:
See:
  • _currentEvent

The last event triggered on the menu.

Type:
  • string

currentMenuItem :BaseMenuItem

Description:

  • The currently selected menu item.

Source:
Overrides:

The currently selected menu item.

Type:

hoverType :string

Description:

  • The type of hoverability for the menu.

    This functions differently for root vs. submenus. Submenus will always inherit their root menu's hoverability.

Source:
Overrides:
See:
  • _hoverType

The type of hoverability for the menu.

This functions differently for root vs. submenus. Submenus will always inherit their root menu's hoverability.

Type:
  • string

hoverDelay :number

Description:

  • The delay time (in miliseconds) used for mouseout events to take place.

    This functions differently for root vs. submenus. Submenus will always inherit their root menu's hover delay.

Source:
Overrides:
See:
  • _hoverDelay

The delay time (in miliseconds) used for mouseout events to take place.

This functions differently for root vs. submenus. Submenus will always inherit their root menu's hover delay.

Type:
  • number

shouldFocus :boolean

Description:

  • A flag to check if the menu's focus methods should actually move the focus in the DOM.

    This will be false unless any of the following criteria are met:

    • The menu's current event is "keyboard".
    • The menu's current event is "character".
    • The menu's current event is "mouse" and the menu's hover type is "dynamic".
Source:
Overrides:

A flag to check if the menu's focus methods should actually move the focus in the DOM.

This will be false unless any of the following criteria are met:

  • The menu's current event is "keyboard".
  • The menu's current event is "character".
  • The menu's current event is "mouse" and the menu's hover type is "dynamic".
Type:
  • boolean

Methods

initialize()

Description:

  • Initializes the menu.

    Initialize will call the BaseMenu's initialize method as well as set up focus, click, hover, 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.

Source:
Overrides:

(protected) _handleKeydown()

Description:

  • Handles keydown events throughout the menu for proper menu use.

    This method exists to assist the _handleKeyup method.

    • 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.
Source:
Overrides:

(protected) _handleKeyup()

Description:

  • Handles keyup events throughout the menu for proper menu use.

    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.
Source:
Overrides:

focusLastNode()

Description:

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

    This includes all open child menu items.

Source:

openChildren()

Description:

  • Open all submenu children.

Source:

focusNextNodeWithCharacter(char)

Description:

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

    This includes all open child menu items.

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

Source:
Parameters:
Name Type Description
char string

The character to look for.

focusParentsNextChild()

Description:

  • Focus the parent menu's next child.

    This will cascade up through to the root menu.

Source:

focusChildsLastNode()

Description:

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

    This will cascade down through to the last open menu.

Source:

(protected) _validate() → {boolean}

Description:

  • Validates all aspects of the menu to ensure proper functionality.

Source:
Overrides:
Returns:
  • The result of the validation.
Type
boolean

(protected) _setDOMElementType(elementType, baseopt, overwriteopt)

Description:

  • Sets DOM elements within the menu.

    Elements that are not stored inside an array cannot be set through this method.

Source:
Overrides:
Parameters:
Name Type Attributes Default Description
elementType string

The type of element to populate.
base HTMLElement <optional>

The element used as the base for the querySelect.
overwrite boolean <optional>
 true

A flag to set if the existing elements will be overwritten.

(protected) _resetDOMElementType(elementType)

Description:

  • Resets DOM elements within the menu.

    Elements that are not stored inside an array cannot be reset through this method.

Source:
Overrides:
Parameters:
Name Type Description
elementType string

The type of element to clear.

(protected) _setDOMElements()

Description:
Source:
Overrides:

(protected) _findRootMenu(menu)

Description:

  • Finds the root menu element.

Source:
Overrides:
Parameters:
Name Type Description
menu BaseMenu

The menu to check.

(protected) _createChildElements()

Description:

  • Creates and initializes all menu items and submenus.

Source:
Overrides:

(protected) _handleFocus()

Description:

  • Handles focus events throughout the menu for proper menu use.

    • Adds a focus listener to every menu item so when it gains focus, it will set the item's containing menu's focus state to "self".
Source:
Overrides:

(protected) _handleClick()

Description:

  • Handles click events throughout the menu for proper use.

    • Adds a pointerdown listener to every menu item that will blur all menu items in the entire menu structure (starting at the root menu) and then properly focus the clicked item.
    • Adds a pointerup listener to every submenu item that will properly toggle the submenu open/closed.
    • Adds a pointerup listener to the menu's controller (if the menu is the root menu) so when it is clicked it will properly toggle open/closed.
Source:
Overrides:

(protected) _handleHover()

Description:

  • Handles hover events throughout the menu for proper use.

    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.

    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 an open submenu item the close method for the submenu item's toggle 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 submenu item, and no submenu is open, no submenu-specific methods will be called.
    • When a pointerleave event triggers on an open submenu item that is not a root-level submenu item the close method for the submenu item's toggle will be called and the submenu item will be focused after a delay set by the menu's hover delay.
    • When a pointerleave event triggers on an open submenu item that is a root-level submenu item no submenu-specific methods will be called.

    Hover Type "off" All pointerenter and pointerleave events are ignored.

Source:
Overrides:

focus()

Description:

  • Focus the menu.

    Sets the menu's focus state to "self" and focusses the menu if the menu's shouldFocus value is true.

Source:
Overrides:

blur()

Description:

  • Unfocus the menu.

    Sets the menu's focus state to "none" and blurs the menu if the menu's shouldFocus vallue is true.

Source:
Overrides:

focusCurrentChild()

Description:

  • Focus the menu's current child.

Source:
Overrides:

focusChild(index)

Description:

  • Focuses the menu's child at a given index.

Source:
Overrides:
Parameters:
Name Type Description
index number

The index of the child to focus.

focusFirstChild()

Description:

  • Focues the menu's first child.

Source:
Overrides:

focusLastChild()

Description:

  • Focus the menu's last child.

Source:
Overrides:

focusNextChild()

Description:

  • Focus the menu's next child.

Source:
Overrides:

focusPreviousChild()

Description:

  • Focus the menu's previous child.

Source:
Overrides:

blurCurrentChild()

Description:

  • Blurs the menu's current child.

Source:
Overrides:

focusController()

Description:

  • Focus the menu's controller.

Source:
Overrides:

focusContainer()

Description:

  • Focus the menu's container.

Source:
Overrides:

closeChildren()

Description:

  • Close all submenu children.

Source:
Overrides:

blurChildren()

Description:

  • Blurs all children and submenu's children.

Source:
Overrides: