Eligible focus

Updated on August 22, 2024

In Baleada Features, any interface that allows arrow keys to transfer focus relies on eligible focus: a group of functions that only focus elements that are considered "eligible" focus targets.

To be considered a "eligible" focus target, an element has to meet one of two conditions:

1. The element's ability is enabled, OR
2. The element's ability is disabled AND the interface was configured to allow focus to transfer to disabled elements

Every interface that relies on eligible focus also includes all of the eligible focus functions in its return value. This guide serves as shared documentation for the eligible focus functions returned by interfaces.

Use eligible focus

Eligible focus is always included in interfaces' return values as an object containing methods. Here are the properties on that object:

All eligible focus methods return a string that describes the element that was focused:

• Methods return enabled if the destination element is enabled
• Methods return disabled if the destination element is disabled
• Methods return none if focus was unsuccessful (e.g. if you use exact to focus a disabled elements when disabled elements are not configured to receive focus)

Narrowing the definition of "eligible"

In some situations, you might want to narrow the definition of "eligible". In other words, you might want to consider other information, beyond just the enabled/disabled state, before confirming that an element is actually an eligible focus target.

For example, if you're building a spreadsheet interface, you might want an easy way to focus the next cell that contains a formula. These app-specific conditions for focus transfer get first-class support from Baleada Features' eligible focus functions.

More specifically, you can use the optional options argument of the eligible focus functions to set up your additional conditions to determine what is considered a "eligible" focus target.

The options argument for each of those functions is an object. Here's a breakdown of that object:

Here's a code example of how to use the eligible focus functions return by useListbox to transfer focus to the next eligible element, where the definition of "eligible" has been narrowed:

import { useListbox } from '@baleada/vue-features'

const listbox = useListbox()

// Imagine a listbox whose list options are split into several groups.
//
// We can pass a custom `toEligibility` option to the 
// `listbox.focus.first` function to transfer focus the first
// enabled element in a specific group.
listbox.focus.first({
  toEligibility: ({ index }) => {
    return myOptions[index].group === 'Group 3'
      ? 'eligible'
      : 'ineligible'
  }
})

Edit doc on GitHub