DirectionCursorMixin

Overview

Purpose: maps direction semantics (e.g., up or down) to item cursor semantics (e.g., go previous or go next).

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

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

Expects the component to provide:

• internal.goNext, internal.goPrevious, internal.goLast, internal.goFirst methods.

Provides the component with:

• internal.goDown, internal.goEnd, internal.goLeft, internal.goRight, internal.goStart, internal.goUp that map to cursor methods. See below.

• canGoDown, canGoLeft, canGoRight, and canGoUp state members to indicate whether it is currently possible for the user to navigate in the indicate directions.

Usage

import DirectionCursorMixin from "elix/src/base/DirectionCursorMixin.js";
class MyElement extends DirectionCursorMixin(HTMLElement) {}

This mixin is designed to complement input mixins that map input events to directions, including ArrowDirectionMixin, KeyboardDirectionMixin, and TouchSwipeMixin. Those mixins can focus exclusively on direction. You can use DirectionCursorMixin to map those directions (e.g., left and right) to item cursor operations (e.g., go previous and go next). The level of abstraction provided by DirectionCursorMixin allows the input mixins to be used that don't deal with a cursor, and want to interpret direction semantics in other ways.

Mapping direction semantics to item cursor semantics

When a direction method with a standard identifier is invoked, a corresponding cursor method is invoked:

• internal.goDown → internal.goNext
• internal.goEnd → internal.goLast
• internal.goLeft → internal.goPrevious (or internal.goNext in right-to-left languages)
• internal.goRight → internal.goNext (or internal.goPrevious in right-to-left languages)
• internal.goStart → internal.goFirst
• internal.goUp → internal.goPrevious

If the component has a rightToLeft property that is true, the mapping of left/right to previous/next is reversed. That is, going left means going to the next item, not the previous one. You can define such a rightToLeft property with LanguageDirectionMixin.

A common use of DirectionCursorMixin will be to connect the KeyboardMixin and KeyboardDirectionMixin above to the Elix ItemsCursorMixin and a mixin like SingleSelectAPIMixin. This effectively creates a chain of actions that convert keyboard events to changes in selection.

Example: a press of the Down arrow key can be handled in the following steps:

1. KeyboardMixin receives the keydown event for the Down arrow key and invokes the component's internal.keydown method.
2. KeyboardDirectionMixin handles internal.keydown for the key, and invokes internal.goDown.
3. DirectionCursorMixin handles internal.goDown and invokes internal.goNext.
4. ItemsCursorMixin handles internal.goNext and updates the current item.
5. SingleSelectAPIMixin raises the selectedindexchange event.

This sequence may seem circuitous, but factoring the behaviors this way allows other forms of interaction. E.g., a separate mixin to handle touch gestures only has to map a "swipe left" gesture to a direction method like goRight in order to patch into this chain. This saves the touch logic from having to know anything about selection.