ui/webui/resources/js/focus_row.ts

// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// clang-format off
import {assert, assertInstanceof} from './assert.js';
import {EventTracker} from './event_tracker.js';
import {hasKeyModifiers, isRTL} from './util.js';
// clang-format on

const ACTIVE_CLASS: string = 'focus-row-active';

/**
 * A class to manage focus between given horizontally arranged elements.
 *
 * Pressing left cycles backward and pressing right cycles forward in item
 * order. Pressing Home goes to the beginning of the list and End goes to the
 * end of the list.
 *
 * If an item in this row is focused, it'll stay active (accessible via tab).
 * If no items in this row are focused, the row can stay active until focus
 * changes to a node inside |this.boundary_|. If |boundary| isn't specified,
 * any focus change deactivates the row.
 */
export class FocusRow {
  root: HTMLElement;
  delegate: FocusRowDelegate|undefined;
  protected eventTracker: EventTracker = new EventTracker();
  private boundary_: Element;

  /**
   * @param root The root of this focus row. Focus classes are
   *     applied to |root| and all added elements must live within |root|.
   * @param boundary Focus events are ignored outside of this element.
   * @param delegate An optional event delegate.
   */
  constructor(root: HTMLElement, boundary: Element|null,
              delegate?: FocusRowDelegate) {
    this.root = root;
    this.boundary_ = boundary || document.documentElement;
    this.delegate = delegate;
  }

  /**
   * Whether it's possible that |element| can be focused.
   */
  static isFocusable(element: Element): boolean {
    if (!element || (element as Element & {disabled?: boolean}).disabled) {
      return false;
    }

    // We don't check that element.tabIndex >= 0 here because inactive rows
    // set a tabIndex of -1.
    let current = element;
    while (true) {
      assertInstanceof(current, Element);

      const style = window.getComputedStyle(current);
      if (style.visibility === 'hidden' || style.display === 'none') {
        return false;
      }

      const parent = current.parentNode;
      if (!parent) {
        return false;
      }

      if (parent === current.ownerDocument ||
          parent instanceof DocumentFragment) {
        return true;
      }

      current = parent as Element;
    }
  }

  /**
   * A focus override is a function that returns an element that should gain
   * focus. The element may not be directly selectable for example the element
   * that can gain focus is in a shadow DOM. Allowing an override via a
   * function leaves the details of how the element is retrieved to the
   * component.
   */
  static getFocusableElement(element: HTMLElement): HTMLElement {
    const withFocusable =
        element as HTMLElement & { getFocusableElement?: () => HTMLElement};
    if (withFocusable.getFocusableElement) {
      return withFocusable.getFocusableElement();
    }
    return element;
  }

  /**
   * Register a new type of focusable element (or add to an existing one).
   *
   * Example: an (X) button might be 'delete' or 'close'.
   *
   * When FocusRow is used within a FocusGrid, these types are used to
   * determine equivalent controls when Up/Down are pressed to change rows.
   *
   * Another example: mutually exclusive controls that hide each other on
   * activation (i.e. Play/Pause) could use the same type (i.e. 'play-pause')
   * to indicate they're equivalent.
   *
   * @param type The type of element to track focus of.
   * @param selectorOrElement The selector of the element
   *    from this row's root, or the element itself.
   * @return Whether a new item was added.
   */
  addItem(type: string, selectorOrElement: string|HTMLElement): boolean {
    assert(type);

    let element;
    if (typeof selectorOrElement === 'string') {
      element = this.root.querySelector<HTMLElement>(selectorOrElement);
    } else {
      element = selectorOrElement;
    }
    if (!element) {
      return false;
    }

    element.setAttribute('focus-type', type);
    element.tabIndex = this.isActive() ? 0 : -1;

    this.eventTracker.add(element, 'blur', this.onBlur_.bind(this));
    this.eventTracker.add(element, 'focus', this.onFocus_.bind(this));
    this.eventTracker.add(element, 'keydown', this.onKeydown_.bind(this));
    this.eventTracker.add(element, 'mousedown', this.onMousedown_.bind(this));
    return true;
  }

  /** Dereferences nodes and removes event handlers. */
  destroy() {
    this.eventTracker.removeAll();
  }

  /**
   * @param sampleElement An element for to find an equivalent
   *     for.
   * @return An equivalent element to focus for
   *     |sampleElement|.
   */
  protected getCustomEquivalent(_sampleElement: HTMLElement): HTMLElement {
    const focusable = this.getFirstFocusable();
    assert(focusable);
    return focusable;
  }

  /**
   * @return All registered elements (regardless of focusability).
   */
  getElements(): HTMLElement[] {
    return Array.from(this.root.querySelectorAll<HTMLElement>('[focus-type]'))
        .map(FocusRow.getFocusableElement);
  }

  /**
   * Find the element that best matches |sampleElement|.
   * @param sampleElement An element from a row of the same
   *     type which previously held focus.
   * @return The element that best matches sampleElement.
   */
  getEquivalentElement(sampleElement: HTMLElement): HTMLElement {
    if (this.getFocusableElements().indexOf(sampleElement) >= 0) {
      return sampleElement;
    }

    const sampleFocusType = this.getTypeForElement(sampleElement);
    if (sampleFocusType) {
      const sameType = this.getFirstFocusable(sampleFocusType);
      if (sameType) {
        return sameType;
      }
    }

    return this.getCustomEquivalent(sampleElement);
  }

  /**
   * @param type An optional type to search for.
   * @return The first focusable element with |type|.
   */
  getFirstFocusable(type?: string): HTMLElement|null {
    const element = this.getFocusableElements().find(
        el => !type || el.getAttribute('focus-type') === type);
    return element || null;
  }

  /** @return Registered, focusable elements. */
  getFocusableElements(): HTMLElement[] {
    return this.getElements().filter(FocusRow.isFocusable);
  }

  /**
   * @param element An element to determine a focus type for.
   * @return The focus type for |element| or '' if none.
   */
  getTypeForElement(element: Element): string {
    return element.getAttribute('focus-type') || '';
  }

  /** @return Whether this row is currently active. */
  isActive(): boolean {
    return this.root.classList.contains(ACTIVE_CLASS);
  }

  /**
   * Enables/disables the tabIndex of the focusable elements in the FocusRow.
   * tabIndex can be set properly.
   * @param active True if tab is allowed for this row.
   */
  makeActive(active: boolean) {
    if (active === this.isActive()) {
      return;
    }

    this.getElements().forEach(function(element) {
      element.tabIndex = active ? 0 : -1;
    });

    this.root.classList.toggle(ACTIVE_CLASS, active);
  }

  private onBlur_(e: FocusEvent) {
    if (!this.boundary_.contains(e.relatedTarget as Element)) {
      return;
    }

    const currentTarget = e.currentTarget as HTMLElement;
    if (this.getFocusableElements().indexOf(currentTarget) >= 0) {
      this.makeActive(false);
    }
  }

  private onFocus_(e: Event) {
    if (this.delegate) {
      this.delegate.onFocus(this, e);
    }
  }

  private onMousedown_(e: MouseEvent) {
    // Only accept left mouse clicks.
    if (e.button) {
      return;
    }

    // Allow the element under the mouse cursor to be focusable.
    const target = e.currentTarget as HTMLElement & {disabled?: boolean};
    if (!target.disabled) {
      target.tabIndex = 0;
    }
  }

  private onKeydown_(e: KeyboardEvent) {
    const elements = this.getFocusableElements();
    const currentElement = FocusRow.getFocusableElement(
        e.currentTarget as HTMLElement);
    const elementIndex = elements.indexOf(currentElement);
    assert(elementIndex >= 0);

    if (this.delegate && this.delegate.onKeydown(this, e)) {
      return;
    }

    const isShiftTab = !e.altKey && !e.ctrlKey && !e.metaKey && e.shiftKey &&
        e.key === 'Tab';

    if (hasKeyModifiers(e) && !isShiftTab) {
      return;
    }

    let index = -1;
    let shouldStopPropagation = true;

    if (isShiftTab) {
      // This always moves back one element, even in RTL.
      index = elementIndex - 1;
      if (index < 0) {
        // Bubble up to focus on the previous element outside the row.
        return;
      }
    } else if (e.key === 'ArrowLeft') {
      index = elementIndex + (isRTL() ? 1 : -1);
    } else if (e.key === 'ArrowRight') {
      index = elementIndex + (isRTL() ? -1 : 1);
    } else if (e.key === 'Home') {
      index = 0;
    } else if (e.key === 'End') {
      index = elements.length - 1;
    } else {
      shouldStopPropagation = false;
    }

    const elementToFocus = elements[index];
    if (elementToFocus) {
      this.getEquivalentElement(elementToFocus).focus();
      e.preventDefault();
    }
    if (shouldStopPropagation) {
      e.stopPropagation();
    }
  }
}

export interface FocusRowDelegate {
  /**
   * Called when a key is pressed while on a FocusRow's item. If true is
   * returned, further processing is skipped.
   * @param row The row that detected a keydown.
   * @return Whether the event was handled.
   */
  onKeydown(row: FocusRow, e: KeyboardEvent): boolean;

  onFocus(row: FocusRow, e: Event): void;

  /**
   * @param sampleElement An element to find an equivalent for.
   * @return An equivalent element to focus, or null to use the
   *     default FocusRow element.
   */
  getCustomEquivalent(sampleElement: HTMLElement): HTMLElement|null;
}

export class VirtualFocusRow extends FocusRow {
  constructor(root: HTMLElement, delegate: FocusRowDelegate) {
    super(root, /* boundary */ null, delegate);
  }

  override getCustomEquivalent(sampleElement: HTMLElement) {
    const equivalent =
        this.delegate ? this.delegate.getCustomEquivalent(sampleElement) : null;
    return equivalent || super.getCustomEquivalent(sampleElement);
  }
}