KeyboardPrefixCursorMixin

Overview

Purpose: handles list box-style prefix typing, in which the user can type a string to move to the first item that begins with that string.

This mixin works in the middle of the Elix render pipeline:

events → methods ➞ setState → render DOM → post-render

Expects the component to provide:

• [internal.state].texts state member containing an array of text strings corresponding to the text content of the current set of items. You can supply that with ItemsTextMixin.
• currentIndex state member, e.g., via ItemsCursorMixin.
• internal.keydown method, usually defined by KeyboardMixin.

Provides the component with:

• Mappings of keyboard events to cursor operations.

Usage

import ItemsCursorMixin from "elix/src/base/ItemsCursorMixin.js";
import ItemsTextMixin from "elix/src/base/ItemsTextMixin.js";
import KeyboardMixin from "elix/src/base/KeyboardMixin.js";
import KeyboardPrefixCursorMixin from "elix/src/base/KeyboardPrefixCursorMixin.js";

class MyElement extends ItemsCursorMixin(
  ItemsTextMixin(KeyboardMixin(KeyboardPrefixCursorMixin(HTMLElement)))
) {}

Example

If this component receives the focus, and you press the "b" or "B" key, the "Banana" item will be selected, because it's the first item that matches the prefix "b". (Matching is case-insensitive.) If you now presses the "l" or "L" key quickly, the prefix to match becomes "bl", so "Blackberry" will be selected.

The prefix typing feature has a one second timeout — the prefix to match will be reset after a second has passed since you last typed a key. If, in the above example, you wait a second between typing "b" and "l", the timeout will reset the prefix to empty. When the "l" key is pressed, "Lemon" will be selected.

If you press the Backspace key, the last character is removed from the prefix under construction. This re-selects the first item that matches the new, shorter prefix. Suppose you type "c", and "Cantaloupe" is selected, then type "h" to select "Cherry". If you now immediately press Backspace (before the aforementioned one second timeout elapses), the prefix will revert to "C", and "Cantaloupe" will be reselected.

Extracting item text

To extract the text of an item, the mixin invokes a method internal.getItemText on each item. The default behavior of that method is to return the item's aria-label attribute, alt attribute or, if that does not exist, its textContent. This allows a component user to customize which text the prefix will be matched against.