Add documentation

[WesCossick]

We can use the README.md file to document the usage/accessibility/behavior/etc.

[WesCossick]

@corymharper Can you comment with a bullet list of design decisions you made for how this Hook behaves according to the WCAG? And can you also share links to relevant places in W3's documentation? I'll use this info when writing the documentation.

[corymharper]

This hook helps to accomplish meeting the following specifications of the WCAG:

Information and Relationships:

• Use of aria-properties and roles to establish relationships amongst elements in the menu

Identify purpose:

• Use of the appropriate roles to identify the purpose of different parts of the menu

Keyboard accessible:

• Sufficient for sections 2.1.1, 2.1.2, 2.1.3.
• All content accessible through the use of a mouse should be accessible through a keyboard
• Content that can be accessed by a keyboard should be able to be escaped by a keyboard
• No specific timing is required for any function

Navigable:

• Sufficient for section 2.4.3
• Focus order is always maintained logically by the application of cohesive keyboard controls

Predictable:

• Sufficient for sections 3.2.1 and 3.2.3
• On focus event never initiate any change in context, only user input
• Controls stay consistent, logical, predictable regardless of context

Name, Role, and Value:

• Sufficient for Situation D
• Uses aria-properties and states to makes the state of the menu clear at all times

Most if not all of methods used to meet WCAG specifications for this hook came from this advisory document: WAI-ARIA Authoring Practices Guide.

The hook matches all of the following specifications

WAI-AAPG: Menu Button Pattern

With focus on the button:

• Enter: opens the menu and places focus on the first menu item.
• Space: Opens the menu and places focus on the first menu item.

WAI-ARIA Roles, States, and Properties:

• The element that opens the menu has role button.
• The element with role button has aria-haspopup set to either menu or true.
• When the menu is displayed, the element with role button has aria-expanded set to true. When the menu is hidden, it is recommended that aria-expanded is not present. If aria-expanded is specified when the menu is hidden, it is set to false.

WAI-AAPG: Menu and Menubar Pattern

Controls

• Enter: Activates the item and closes the menu.
• Down Arrow: When focus is in a menu, moves focus to the next item, and wraps from the last to the first.
• Up Arrow: When focus is in a menu, moves focus to the previous item, and wraps from the first to the last.
• Escape: Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent menuitem, from which the menu was opened.
• Tab: Moves focus to the next element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.
• Shift + Tab: Moves focus to the previous element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.

Things this hook does not do:

• It does not currently provide props for the element that contains the menu items, generally this means it is up to the developer to give the role of "menu" to the correct element
• It does not currently support submenus of menu items
• It only supports menus, not menu bars. That distinction according to WAI-ARIA is:

A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. A menu is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a sub menu, or by invoking a command, such as Shift + F10 in Windows, that opens a context specific menu. When a user activates a choice in a menu, the menu usually closes unless the choice opened a submenu.

A menu that is visually persistent is a menubar. A menubar is typically horizontal and is often used to create a menu bar similar to those found near the top of the window in many desktop applications, offering the user quick access to a consistent set of commands.