DisclosureMenu

An accessible disclosure menu in the DOM.

Note

This is a subclass of BaseMenu.

Constructor

Constructs a new DisclosureMenu.

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

The constructor will call BaseMenu's constructor with the provided options. It will also populate the optionalSupport property and 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.	"button"
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".	"show"
options.closeClass	string, string[], null	The class to apply when a menu is "closed".	"hide"
options.transitionClass	string, string[], null	The class to apply when a menu is transitioning between "open" and "closed" states.	transitioning
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	DisclosureMenu, 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.optionalKeySupport	boolean	A flag to add optional keyboard support (Arrow keys, Home, and End) to the menu.	false
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.

DisclosureMenu.initialize();

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

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 DisclosureMenu class.

_MenuType protected

The class to use when generating submenus.

DisclosureMenu._MenuType; // Default: `DisclosureMenu`.

Type

Class

_MenuItemType protected

The class to use when generating menu items.

DisclosureMenu._MenuItemType; // Default: `DisclosureMenuItem`.

Type

Class

_MenuToggleType protected

The class to use when generating menu toggles.

DisclosureMenu._MenuToggleType; // Default: `DisclosureMenuToggle`.

Type

Class

_currentChild protected

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

DisclosureMenu._currentChild; // Default: `-1`.

Type

number

_optionalSupport protected

A flag to add optional keyboard support (Arrow keys, "Home", and "End") to the menu.

DisclosureMenu._optionalSupport; // Default: `false`.

Type

boolean

Getters and Setters

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

optionalKeySupport

A flag to add optional keyboard support (Arrow keys, "Home", and "End") to the menu.

getter

/**
 * @type {boolean}
 *
 * @see _optionalSupport
 */
DisclosureMenu.optionalKeySupport;

setter

/**
 * @type {boolean}
 */
DisclosureMenu.optionalKeySupport = true;

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

Methods

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

_validate protected

Validates all aspects of the menu to ensure proper functionality.

DisclosureMenu._validate();

The validation method will call BaseMenu's validation method as well as validate the optionalKeySupport property.

Returns

Type	Description
boolean	The result of the validation.

_handleClick protected

Handles click events throughout the menu for proper use.

DisclosureMenu._handleClick();

This method will do the following:

• Adds all event listeners listed in BaseMenu's _handleClick method.
• Adds a pointerup listener to the document so if the user clicks outside of the menu it will close if it is open.

_handleKeydown protected

Handles keydown events throughout the menu for proper menu use.

DisclosureMenu._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: "Space", "Enter", and "Escape".
  • If optional keyboard support is enabled, blocks propagation on the following keys: "ArrowUp", "ArrowRight", "ArrowDown", "ArrowLeft", "Home", and "End".

_handleKeyup protected

Handles keyup events throughout the menu for proper menu use.

DisclosureMenu._handleKeyup();

Adds all keyup listeners from BaseMenu's _handleKeyup method.

Adds the following keybindings (explanations are taken from the WAI ARIA Practices Example Disclosure for Navigation Menus:

Key	Function
Tab or Shift + Tab	Move keyboard focus among top-level buttons, and if a dropdown is open, into and through links in the dropdown.
Space or Enter	If focus is on a disclosure button, activates the button, which toggles the visibility of the dropdown. If focus is on a link: If any link has aria-current set, removes it. Sets aria-current="page" on the focused link. Activates the focused link.
Escape	If a dropdown is open, closes it and sets focus on the button that controls that dropdown.
Down Arrow or Right Arrow (Optional})	If focus is on a button and its dropdown is collapsed, and it is not the last button, moves focus to the next button. if focus is on a button and its dropdown is expanded, moves focus to the first link in the dropdown. If focus is on a link, and it is not the last link, moves focus to the next link.
Up Arrow or Left Arrow (Optional})	If focus is on a button, and it is not the first button, moves focus to the previous button. If focus is on a link, and it is not the first link, moves focus to the previous link.
Home (Optional)	If focus is on a button, and it is not the first button, moves focus to the first button. If focus is on a link, and it is not the first link, moves focus to the first link.
End (Optional)	If focus is on a button, and it is not the last button, moves focus to the last button. If focus is on a link, and it is not the last link, moves focus to the last link.

The optional keybindings are controlled by the menu's optionalKeySupport value.