Eligible picking

Updated on August 22, 2024

In Baleada Features, any interface that allows you to select or activate one or more elements relies on eligible picking: a group of functions that only pick elements that are considered "eligible".

To be considered "eligible", an element's ability must be enabled.

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

Use eligible picking

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

All eligible picking methods return a string that describes the element that was picked to:

• Methods return enabled if the destination element is enabled
• Methods return none if picking was unsuccessful (e.g. if you use exact to try and pick a disabled element)
• Unlike the eligible focus methods, eligible picking methods never return disabled, because picking disabled elements is never allowed.

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 picking target.

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

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

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 picking functions return by useListbox to select 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 an index of `-1` and a custom `toEligibility` option
// to the `listbox.select.next` function to select the first
// enabled element in a specific group.
listbox.select.next(-1, {
  toEligibility: ({ index }) => {
    return myOptions[index].group === 'Group 3'
      ? 'eligible'
      : 'ineligible'
  }
})

Edit doc on GitHub