Add tab helper (to simulate "tabbing" through focusable elements)

addon-test-support/@ember/test-helpers/-utils.ts

@@ -8,6 +8,7 @@ const HAS_PROMISE =
   Promise !== RSVP.Promise;
 
 import PromisePolyfill from './-internal/promise-polyfill';
+import isFormControl from './dom/-is-form-control';
 
 const _Promise: typeof Promise = HAS_PROMISE
   ? Promise
@@ -53,3 +54,29 @@ export function runDestroyablesFor(object: any, property: string): void {
 export function isNumeric(n: string): boolean {
   return !isNaN(parseFloat(n)) && isFinite(Number(n));
 }
+
+/**
+  Checks if an element is considered visible by the focus area spec.
+
+  @private
+  @param {Element} element the element to check
+  @returns {boolean} `true` when the element is visible, `false` otherwise
+*/
+export function isVisible(element: Element): boolean {
+  let styles = window.getComputedStyle(element);
+  return styles.display !== 'none' && styles.visibility !== 'hidden';
+}
+
+/**
+  Checks if an element is disabled.
+
+  @private
+  @param {Element} element the element to check
+  @returns {boolean} `true` when the element is disabled, `false` otherwise
+*/
+export function isDisabled(element: HTMLElement): boolean {
+  if (isFormControl(element)) {
+    return (element as HTMLInputElement).disabled;
+  }
+  return false;
+}

addon-test-support/@ember/test-helpers/dom/-is-focusable.ts

@@ -1,7 +1,9 @@
 import isFormControl from './-is-form-control';
 import { isDocument, isContentEditable, isWindow } from './-target';
 
-const FOCUSABLE_TAGS = ['A'];
+// For reference:
+// https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute
+const FOCUSABLE_TAGS = ['A', 'SUMMARY'];
 
 type FocusableElement = HTMLAnchorElement;
 

addon-test-support/@ember/test-helpers/dom/fire-event.ts

@@ -96,7 +96,7 @@ function fireEvent(
 
   let event;
   if (isKeyboardEventType(eventType)) {
-    event = buildKeyboardEvent(eventType, options);
+    event = _buildKeyboardEvent(eventType, options);
   } else if (isMouseEventType(eventType)) {
     let rect;
     if (element instanceof Window && element.document.documentElement) {
@@ -185,8 +185,12 @@ function buildMouseEvent(type: MouseEventType, options: any = {}) {
   return event;
 }
 
+// @private
 // eslint-disable-next-line require-jsdoc
-function buildKeyboardEvent(type: KeyboardEventType, options: any = {}) {
+export function _buildKeyboardEvent(
+  type: KeyboardEventType,
+  options: any = {}
+) {
   let eventOpts: any = assign({}, DEFAULT_EVENT_OPTIONS, options);
   let event: Event | undefined;
   let eventMethodName: 'initKeyboardEvent' | 'initKeyEvent' | undefined;

addon-test-support/@ember/test-helpers/dom/tab.ts

@@ -0,0 +1,246 @@
+import getRootElement from './get-root-element';
+import settled from '../settled';
+import fireEvent, { _buildKeyboardEvent } from './fire-event';
+import { isDocument } from './-target';
+import { __blur__ } from './blur';
+import { __focus__ } from './focus';
+import { Promise, isVisible, isDisabled } from '../-utils';
+
+const SUPPORTS_INERT = 'inert' in Element.prototype;
+const FALLBACK_ELEMENTS = ['CANVAS', 'VIDEO', 'PICTURE'];
+
+/**
+  Gets the active element of a document. IE11 may return null instead of the body as
+  other user-agents does when there isn’t an active element.
+  @private
+  @param {Document} ownerDocument the element to check
+  @returns {HTMLElement} the active element of the document
+*/
+function getActiveElement(ownerDocument: Document): HTMLElement {
+  return (ownerDocument.activeElement as HTMLElement) || ownerDocument.body;
+}
+
+interface InertHTMLElement extends HTMLElement {
+  inert: boolean;
+}
+
+/**
+  Compiles a list of nodes that can be focused. Walkes the tree, discardes hidden elements and a few edge cases. To calculate the right.
+  @private
+  @param {Element} root the root element to start traversing on
+  @returns {Array} list of focusable nodes
+*/
+function compileFocusAreas(root: Element = document.body) {
+  let { ownerDocument } = root;
+
+  if (!ownerDocument) {
+    throw new Error('Element must be in the DOM');
+  }
+
+  let activeElment = getActiveElement(ownerDocument);
+  let treeWalker = ownerDocument.createTreeWalker(
+    root,
+    NodeFilter.SHOW_ELEMENT,
+    {
+      acceptNode: (node: HTMLElement) => {
+        // Only visible nodes can be focused, with, at least, one exception; the "area" element.
+        // reference: https://html.spec.whatwg.org/multipage/interaction.html#data-model
+        if (node.tagName !== 'AREA' && isVisible(node) === false) {
+          return NodeFilter.FILTER_REJECT;
+        }
+
+        // Reject any fallback elements. Fallback elements’s children are only rendered if the UA
+        // doesn’t support the element. We make an assumption that they are always supported, we
+        // could consider feature detecting every node type, or making it configurable.
+        let parentNode = node.parentNode as HTMLElement | null;
+        if (
+          parentNode &&
+          FALLBACK_ELEMENTS.indexOf(parentNode.tagName) !== -1
+        ) {
+          return NodeFilter.FILTER_REJECT;
+        }
+
+        // Rejects inert containers, if the user agent supports the feature (or if a polyfill is installed.)
+        if (SUPPORTS_INERT && (node as InertHTMLElement).inert) {
+          return NodeFilter.FILTER_REJECT;
+        }
+
+        if (isDisabled(node)) {
+          return NodeFilter.FILTER_REJECT;
+        }
+
+        // Always accept the 'activeElement' of the document, as it might fail the next check, elements with tabindex="-1"
+        // can be focused programtically, we'll therefor ensure the current active element is in the list.
+        if (node === activeElment) {
+          return NodeFilter.FILTER_ACCEPT;
+        }
+
+        // UA parses the tabindex attribute and applies its default values, If the tabIndex is non negative, the UA can
+        // foucs it.
+        return node.tabIndex >= 0
+          ? NodeFilter.FILTER_ACCEPT
+          : NodeFilter.FILTER_SKIP;
+      },
+    },
+    false
+  );
+
+  let node: Node | null;
+  let elements: HTMLElement[] = [];
+
+  while ((node = treeWalker.nextNode())) {
+    elements.push(node as HTMLElement);
+  }
+
+  return elements;
+}
+
+/**
+  Sort elements by their tab indices.
+  As older browsers doesn't necessarily implement stabile sort, we'll have to
+  manually compare with the index in the original array.
+  @private
+  @param {Array<HTMLElement>} elements to sort
+  @returns {Array<HTMLElement>} list of sorted focusable nodes by their tab index
+*/
+function sortElementsByTabIndices(elements: HTMLElement[]): HTMLElement[] {
+  return elements
+    .map((element, index) => {
+      return { index, element };
+    })
+    .sort((a, b) => {
+      if (a.element.tabIndex === b.element.tabIndex) {
+        return a.index - b.index;
+      } else if (a.element.tabIndex === 0 || b.element.tabIndex === 0) {
+        return b.element.tabIndex - a.element.tabIndex;
+      }
+      return a.element.tabIndex - b.element.tabIndex;
+    })
+    .map((entity) => entity.element);
+}
+
+/**
+  @private
+  @param {Element} root The root element or node to start traversing on.
+  @param {HTMLElement} activeElement The element to find the next and previous focus areas of
+  @returns {object} The next and previous focus areas of the active element
+ */
+function findNextResponders(root: Element, activeElement: HTMLElement) {
+  let focusAreas = compileFocusAreas(root);
+  let sortedFocusAreas = sortElementsByTabIndices(focusAreas);
+  let elements = activeElement.tabIndex === -1 ? focusAreas : sortedFocusAreas;
+
+  let index = elements.indexOf(activeElement);
+  if (index === -1) {
+    return {
+      next: sortedFocusAreas[0],
+      previous: sortedFocusAreas[sortedFocusAreas.length - 1],
+    };
+  }
+
+  return {
+    next: elements[index + 1],
+    previous: elements[index - 1],
+  };
+}
+
+/**
+  Emulates the user pressing the tab button.
+
+  Sends a number of events intending to simulate a "real" user pressing tab on their
+  keyboard.
+
+  @public
+  @param {Object} [options] optional tab behaviors
+  @param {boolean} [options.backwards=false] indicates if the the user navigates backwards
+  @param {boolean} [options.unRestrainTabIndex=false] indicates if tabbing should throw an error when tabindex is greater than 0
+  @return {Promise<void>} resolves when settled
+
+  @example
+  <caption>
+    Emulating pressing the `TAB` key
+  </caption>
+  tab();
+
+  @example
+  <caption>
+    Emulating pressing the `SHIFT`+`TAB` key combination
+  </caption>
+  tab({ backwards: true });
+*/
+export default function triggerTab(options?: {
+  backwards: boolean;
+  unRestrainTabIndex: boolean;
+}): Promise<void> {
+  return Promise.resolve()
+    .then(() => {
+      let backwards = (options && options.backwards) || false;
+      let unRestrainTabIndex = (options && options.unRestrainTabIndex) || false;
+      return triggerResponderChange(backwards, unRestrainTabIndex);
+    })
+    .then(() => {
+      return settled();
+    });
+}
+
+/**
+  @private
+  @param {boolean} backwards when `true` it selects the previous foucs area
+  @param {boolean} unRestrainTabIndex when `true`, will not throw an error if tabindex > 0 is encountered
+  @returns {Promise<void>} resolves when all events are fired
+ */
+function triggerResponderChange(
+  backwards: boolean,
+  unRestrainTabIndex: boolean
+): Promise<void> {
+  let root = getRootElement();
+  let ownerDocument: Document;
+  let rootElement: HTMLElement;
+  if (isDocument(root)) {
+    rootElement = root.body;
+    ownerDocument = root;
+  } else {
+    rootElement = root as HTMLElement;
+    ownerDocument = root.ownerDocument as Document;
+  }
+
+  let keyboardEventOptions = {
+    keyCode: 9,
+    which: 9,
+    key: 'Tab',
+    code: 'Tab',
+    shiftKey: backwards,
+  };
+
+  return Promise.resolve()
+    .then(() => {
+      let activeElement = getActiveElement(ownerDocument);
+      let event = _buildKeyboardEvent('keydown', keyboardEventOptions);
+      let defaultNotPrevented = activeElement.dispatchEvent(event);
+
+      if (defaultNotPrevented) {
+        // Query the active element again, as it might change during event phase
+        activeElement = getActiveElement(ownerDocument);
+        let target = findNextResponders(rootElement, activeElement);
+        if (target) {
+          if (backwards && target.previous) {
+            __focus__(target.previous);
+          } else if (!backwards && target.next) {
+            __focus__(target.next);
+          } else {
+            __blur__(activeElement);
+          }
+        }
+      }
+    })
+    .then(() => {
+      let activeElement = getActiveElement(ownerDocument);
+      fireEvent(activeElement, 'keyup', keyboardEventOptions);
+
+      if (!unRestrainTabIndex && activeElement.tabIndex > 0) {
+        throw new Error(
+          `tabindex of greater than 0 is not allowed. Found tabindex=${activeElement.tabIndex}`
+        );
+      }
+    });
+}

addon-test-support/@ember/test-helpers/index.ts

@@ -39,6 +39,7 @@ export {
 // DOM Helpers
 export { default as click } from './dom/click';
 export { default as doubleClick } from './dom/double-click';
+export { default as tab } from './dom/tab';
 export { default as tap } from './dom/tap';
 export { default as focus } from './dom/focus';
 export { default as blur } from './dom/blur';

tests/helpers/events.js

@@ -1,3 +1,5 @@
+import { get } from '@ember/object';
+
 // from https://mdn.mozilla.org/en-US/docs/Web/Events
 export const KNOWN_EVENTS = Object.freeze([
   'abort',
@@ -189,7 +191,8 @@ export function instrumentElement(element, logOptionsProperties) {
       if (!element.hasAttribute('data-skip-steps')) {
         if (logOptionsProperties) {
           for (var prop of logOptionsProperties) {
-            step += ` ${e[prop]}`;
+            // needs to be get so prop-paths can be used, such as "target.id"
+            step += ` ${get(e, prop)}`;
           }
         }
         assert.step(step);