JavaScript Keyboard Operations Needs and Solutions

[reboottime]

Overview

This note contains two topics

• Introduce JavaScript keyboard events fundamentals
• Introduce commonly used keyboard operation needs and corresponding solutions on React stack.

---

Fundamentals

Keyboard events

Keyboard events and their triggering order

• Triggering order: keydown, keypress, keyup
• Details about these events
  • keydown: It fires when any key is pressed down. Practically most used, as the key down event has the maximum coverage of keys to produce the contextual information.
  • keypress: It fires only when a key that produces a character value is pressed down. For example, if you press the key a, this event will fire as the key a produces a character value of 97. On the other hand, this event will not fire when you press the shift key as it doesn't produce a character value.
  • keyup: It fires when any key is released.

Frequently Used keyboard key (event.key)

export const KEYBOARD_KEYS = {
  arrowDown: 'ArrowDown',
  arrowUp: 'ArrowUp',
  escape: 'Escape',
  enter: 'Enter',
  tab: 'Tab',
  space: ' '
};

• Why do we use event.key as the way to detect which keyboard is clicked? Originally, there are four ways to identify which keyboard was clicked, the key, keyCode, the code, and 'which`.
  • It is because the last three are depretected , and the key property has the widest browser support.
  • The exception to usingcode is when you are detecting a direction( not fully tested)

References :

1. https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/
2. https://stackoverflow.com/questions/5597060/detecting-arrow-key-presses-in-javascript

[reboottime]

Fundamentals

Relevant default behaviors on keyboard event or elements

• "button"

  • To the button elements, pressing the Enter or Space key triggers the onClick handler automatically. That means a button element should not have both 'onClickandonKeyDown` handlers if the two handlers perform the same functionality.
  • For elements that have a role as button and tabIndex value, you can't depend on the role and tabIndex as a way to call for onKeydown behavior.

• select: Select supports navigating options via pressing arrow up/down key, and toggle opening status via pressing Enter or Space key

• a: pressing a focused a , browser redirect users to the specified page on href property.

• arrowUp/Down/Right/left: If the default behavior of arrow up/down event is not prevented, pressing arrow up/down scroll pages vertically or horizontally.

[reboottime]

Keyboard Practices

Supporting keyboard operation on webpages is a essential part of accessibility. Keyboard navigation involves keyboard navigation and operations.

Let's take building a Select component as an example, we need

• Support navigating options vertically,
• Select an option via pressing Space or Enter key,
• Support returning focus back to the Select trigger after closing expanded options after pressing ESC key

Keyboard Navigation

1. Navigate vertically among focusable elements
   • To view a live example, please navigate the Sort By select on this page,
   • And here is the sample code
   • Under the hood

export const handleVerticalNavigation =  (e: React.KeyboardEvent<HTMLElement> | KeyboardEvent) => {
  const targetElement = e.target as HTMLElement;

  const nextElementSibling = targetElement.nextElementSibling as HTMLElement;
  const prevElementSibling = targetElement.previousElementSibling as HTMLElement;

  const firstElementSibling = targetElement.parentElement?.firstChild as HTMLElement;
  const lastElementSibling = targetElement.parentElement?.lastChild as HTMLElement;

  if (e.key === KEYBOARD_KEYS.arrowDown) {
    e.preventDefault();

    if (targetElement === lastElementSibling) {
      firstElementSibling.focus();
    } else {
      nextElementSibling.focus();
    }
  }

  if (e.key === KEYBOARD_KEYS.arrowUp) {
    e.preventDefault();

    if (targetElement === firstElementSibling) {
      lastElementSibling.focus();
    } else {
      prevElementSibling.focus();
    }
  }
};

2. Similarly, to navigate the horizontally, we detect the arrowLeft and arrowRight event.
3. Navigating using Tab key.

   • The Tab only effects on focusable html elements, such as button, input, etc

   • When an element is Tabbed, the element is on focus state.

   • To add Tab support on elements that are not supported by browsers natively, specifying a tabIndex is the solution
     For example:

     • source code
       
     • You might have already noticed that there is a role=button on the span element; the purpose is to improve the accessibility for screen readers, as the role is more precise to screen readers the purpose of that span.

[reboottime]

Keyboard Practices

Keyboard Operations: Select, Close, and Lock focus

• Common keyboard operation needs

  • Users may want to select an option when pressing the Enter or Space Key
  • Close the select options by pressing ESC and return the focus to the "Select" trigger button
  • Lock the navigation just inside the select options. That means when the "select options" is expanded, navigating around using the Tab key should not be able to visit other focusable elements outside of select options.

• Lock Focus and Return Focus back: It is annoying when you navigate inside a modal, yet a tag outside of your modal dialog is focused. While we can reinvent a wheel, here the react-focus-lock is a mature solution on locking focus

  • Supports locking focus for an area of elements
  • Supports returning focus back to original elements before the user entered the focus locking area

• Selecting via Enter or Space key:

  • One dumb way is to bind the onKeydown event on element, and detect the event key to decide ignore the event or do something
  • The smart way is DRY, do not repeat yourself via extracting the event.key logic and utilize HOC in JavaScript.
    • Extract HOC function

    export const handleEnterSpaceKeydown = (handler: React.KeyboardEventHandler) => {
       return function (e: React.KeyboardEvent<HTMLElement>) {
         if (SELECT_KEYS.includes(e.key)) {
           handler(e);
         }
       };
     };

    • Use our smart function

    export const Tag: React.FC<Props> = ({
          clickable,
          children,
          onClick,
        }) => (
          <span
            className={classNames('tag', 'border-rounded--large', 'fw-semi-bold', {
              'tag--clickable': clickable,
            })}
            {...(clickable && {
              onClick: onClick,
              onKeyDown: handleEnterSpaceKeydown(onClick as React.KeyboardEventHandler),
              role: 'button',
              tabIndex: 0,
            })}
          >
            {children}
          </span>
     );

• Close modal pressing ESC key

  useEffect(() => {
    const handler = handleEscapeKeydown(onClose);

    // @todo: resolve never
    document.addEventListener('keydown', handler);

    return () => {
      document.removeEventListener('keydown', handler);
    };
  }, []);