boma-digital / ember-select-box

:capital_abcd: A faux select box for Ember apps

@zestia/ember-select-box

This addon mimics a native select box. It is lightweight and highly flexible.

Installation

ember install @zestia/ember-select-box

Demo

https://zestia.github.io/ember-select-box

Features

• Mimics a native select box, but easily stylable ✔︎
• Navigatable options and groups ✔︎
• Valid Combobox / Listbox ✔︎
• Any HTML you want ✔︎
• Full control at all times with the API ✔︎
• No configuration options ✔︎
• Very few issues over many years of Ember! ✔︎
• Customisable filtering built in ✔︎

Notes

• This addon intentionally does not come with any styles.

Example

<SelectBox @value='Foo' @onChange={{this.handleChange}} as |sb|>
  <sb.Trigger>
    {{sb.value}}
  </sb.Trigger>
  <sb.Options>
    <sb.Option @value='Foo'>
      Foo
    </sb.Option>
  </sb.Options>
</SelectBox>

How it works

This addon will render a Combobox if you utilise the Trigger or Input component.
Otherwise it will render a Listbox.

View more details

Differences to Native Select Boxes

1. When using the arrow keys on a native select box, it will stop dead when you reach the end or the beginning. Whereas, with this addon it will cycle through the options. This is following advice from w3.org.
2. When mousing-out of a native single select box, the current option is forgotten. Whereas, with this addon the option stays current. This is because, the select box still has focus and as such, is still receptive to user input - like pressing Enter to select that option.
3. When using a multiple native select box, selecting an option only selects that 1 option. Whereas, with this addon, the item is added if it isn't already in the collection and removed if it is (although this can be customised with @onBuildSelection)

Differences to Ember Power Select

1. With EPS you have to provide it a data structure which the addon uses to draw your UI. Whereas, with this addon the markup provides the structure - the same way you do with a native select box in HTML.
2. You tell EPS which component to render for each option. Whereas with this addon you can utilise Named Blocks.

SelectBox

Arguments

@onReady

Optional. Fired when the select box is ready. A useful opportunity to get access to the select box's API which is passed as a parameter.

@value

Required. Used to determine which option(s) are selected. This value is compared to the @value's of the option components.

@options

Optional. Use this provide an initial set of options. See yielded options

@onChange

Required. Fired when a selection is made (that is, an option is clicked, or enter/space is pressed) and the new value is different to the old value.

@onSelect

Optional. Similar to @onChange but fires regardless as to whether the value changed or not.

@onSearch

Optional. The default search behaviour filters down the @options. Use this action to perform a custom search or see Filtering.

@disabled

Optional. If true, the component will be unfocusable and all child components (Trigger, Input and Options) will also be disabled.

@multiple

Optional. If true, @value is expected to be an array. If an option's value is included in that array, it will be considered 'selected'.

@onBuildSelection

Optional. Fired whenever a selection is made. This function receives the values most recently selected, and the previously selected values. The return value is then used as the final selection. This is primarily used to customise select boxes where @multiple is true - because the behaviour for a selection is undefined and totally depends on your use-case.

@onOpen

Optional. Fired when the select box is opened

@onWillClose

Optional. The select box will close when the user has finished interacting with it. This means, it has lost focus, or the the user aborted their mouse click, or they pressed Escape. Returning false will prevent this behaviour, keeping the select box open. You are then free to manually close the select box using the API.

@onClose

Optional. Fired when the select box is closed

@onActivate

Optional. Fired when an option is moused over or focused via the keyboard controls

API

select

Mimics the user making a selection, and so @onChange may fire.

update

Updates the select box with a new value(s). @onChange will not fire.

open

Opens the select box.

toggle

Opens or closes the select box

close

Closes the select box

element

The element of the select box

value

The selected value(s) of the select box

isBusy

True if the select box is waiting for a search to finish

isOpen

Whether the select box is open

query

The query used to produce the latest search results. (This may be different to the current value in the text input).

options

These are the same options as given to the component via @options, yielded back to you. Unless a search has run, in which case they will be the return value from @onSearch

Option

Arguments

@value

Required. The value of the option.

@disabled

Optional. Prevents the option from being activated or selected.

API

id

The unique id of the option element

value

The value of the option

index

The index of the option amongst the options

isActive

True if the option is active

isDisabled

Whether or not the option is currently disabled

isSelected

Whether or not the option is currently selected

Group

Arguments

@label

Required. The group label (similar to the native optgroup)

Options

A container element to house each option. If no Trigger or Input is rendered, then this will be a Listbox.

Input

A combobox, which by default filters down the available @options. Customise this behaviour by providing @onSearch.

Trigger

A combobox, which toggles the select box open/closed.

Filtering

Since filtering options down is a common requirement, this addon comes with a utility to help.

View example

import { filter } from '@zestia/ember-select-box';

/**
 * [{
 *   groupLabel: 'Group 1',
 *   items: [{
 *     id: 1,
 *     name: 'Foo'
 *   }, {
 *     id: 2,
 *     name: 'Bar'
 *   }]
 *  }, {
 *   groupLabel: 'Group 2',
 *   items: [{
 *     id: 3,
 *     name: 'Baz'
 *   }, {
 *     id: 4,
 *     name: 'Qux'
 *   }]
 * }]
 */

@action
handleSearch(query) {
  return filter(this.args.options)
    .by('name')
    .groups('items')
    .dropEmptyGroups()
    .query(query)
    .run();
}

filter(<array>)

Accepts an array of options to filter down.

query(<string>)

Required. The query string used to filter each option

by(<string|array|function(option)>)

Optional. By default the value of each option will be used for filtering. Provide a string to pick a specific key from an option. Provide an array to filter by multiple properties. Or provide a function to pluck your own value.

groups(<string>)

Optional. Calling this tells the filter function that your data structure contains groups of options, and the key to where those options can be found.

dropEmptyGroups()

Optional. Tells the filter to exclude groups with no options

using(<function(string, query)>)

Optional. By default each option will be included in the results if it contains the query string. Use this function to provide your own logic to compute whether or not an option should be included.

run()

Kicks off the filter you've configured