vigour-io/aim

Dependency free focus manager with built-in universal key navigation.

• Aim
  • What?
  • Examples
  • Events
    • onFocus(target)
    • onBlur(target)
    • onEnter(target)
  • API
    • currentFocus
    • x
    • xEnd
    • y
    • yEnd
    • children
    • direction
    • up
    • down
    • left
    • right
    • handleKeyEvent
    • register
    • unregister
    • get
    • focus

Aim

Dependency free focus manager with built-in universal key navigation.

npm i --save aim

What?

Register your focusable targets with Aim and Aim will map these into a virtual table-esque view.

Aim will now listen for key events, delegate these to the currently focused target and execute default cursor navigation if not prevented by target handlers.

Examples

aim.register({
  onFocus (target) {
    // fires when target is focused
    // return false to prevent focus
  },
  onBlur (target) {
    // fires when target is unfocused 

  },
  onRight (target) {
    // fires when right is pressed
    // return false to prevent default behaviour (ie. moving cursor to the right)
  },
  onEnter (target) {
    // fires when enter is pressed
  }
}, [0, 0, 1])

Events

onFocus(target)

Fires when target is focused.

Param	Type	Description
target	Object	Registered target.

onBlur(target)

Fires on target when removing focus.

Param	Type	Description
target	Object	Registered target.

onEnter(target)

Fires on focused target when user presses "enter".

Param	Type	Description
target	Object	Registered target.

API

currentFocus

Current focused leaf.

x

X start position of virtual view.

xEnd

X end position of virtual view.

y

Y start position of virtual view.

yEnd

Y end position of virtual view.

children

Children of top level view.

direction

Top level direction of layout, y being column, x being row.

up

Focus one item upward.

down

Focus one item downward.

left

Focus one to the left.

right

Focus one to the right.

handleKeyEvent

Will delegate given event to currently focused item.

Parameters

• e Event

Examples

window.addEventListener('keydown', e => aim.handleKeyEvent(e))

register

Registers target on given position.

Parameters

• target Object Target containing handlers.
• position Array<Number> Coordinates for position.

Returns Object target

unregister

Unregisters target.

Parameters

• target Object Target to unregister.

get

Gets target on given position.

Parameters

• position Array<Number> Coordinates for position.

Returns (Object | undefined) target

focus

Focuses passed target.

Parameters

• target Object Target to focus.

Returns (Object | undefined) target